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Nan 

P 

Parametres 

Page 

Categaorie 

ADOPT 

P 

srcpt: point; var dstpt: point 

E-67 

POINTS 

BACKCOLOR 

P 

color :longint 

E-47 

COLOR 

BACKPAT 

P 

pat: pattern — 

E-40 

GRAFPORT 

BEEP 

P 

wavel engt h mi cr oseconds; dur at i on : mi 1 1 i seconds 

F-07 

SPEAKER 

BUSYDELAY 

P 

delay :milli seconds 

F-05 

CURSOR 

BUSYIHAGE 

P 

hotx: pixels; hoty : pixels; height: cursor height; 

F-05 

CURSOR 

BUSYIMAGE (bis) 


data ; cursorptr; mask : cursorptr 

F-05 

CURSOR 

CHARWIDTH 

F 

(ch:char) -.integer 

E-45 

TEXT 

CLIPRECT 

P 

r :rect 

E-40 

GRAFPORT 

CLOSEPICTURE 



E-64 

PICTURES 

CLOSEPOLY 



E-65 

POLYGONS 

CLOSEPORT 


gp ; grafptr 

E-37 

GRAFPORT 

LOSERGN 


dstrgn : rgnhandle 

E-57 

REGIONS 

COLORBIT 


wichbit: integer 

E-47 

COLOR 

CONTRAST 


screencontrast 

F-06 

SCREEN 

COPYBITS 

P 

srcbits, dstbits : bitmap: srcrect, dstrect :rect 

E-62 

TRANSFERT 

COPYBITS (bis) 


mode: integer; rnaskr gn : r gnhandl e 

E-62 

TRANSFERT 

COPYRGN 

P 

srcrgn, dstrgn-.rgnhandle ; 

E-56 

REGIONS 

CURSORIMAGE 

P 

hotx : pixels; hoty: pixels? heiqht:Cursorheiaht; 

F-05 

CURSOR 

CURSORIMAGE (bis) 


proceduredata: cursorptr; mask : cursorptr 

F-05 

CURSOR 

CURSORTRACKING 

P 

track: boolean 

F-05 

CURSOR 

DATETIME 

P 

var date:datearray 

F-14 

TIME 

DATETOTIME 

P 

date:datearray ; var time: seconds 

F-14 

TIME 

DIFFRGN 

P 

srcrgna, srcrgnb, dstrgn:rgnhandle 

E-59 

REGIONS 

DIMCONTRAST j 

F 

: screencontrast 

F-06 

SCREEN 

DISPOSERGN | 

P 

rgn : rgnhandle 

E-56 

REGIONS 

DRAWCHAR 

P 

ch : char 

E-45 

TEXT 

DRAWPICTURE 

P 

mypicture:pichandle; dstrect : rect 

E-64 

PICTURES 

RAWSTRING 

P 

S:str255 

E-45 

TEXT 

l-jRAWTEXT 

P 

textbuf :qdptr; firstbyte, bytecount integer 

E-45 

TEXT 

EMPTYRECT 

F 

(r : rect) : boolean 

E-49 

RECTANGLE 

EMPTYRGN 

F 

(rgn : rgnhandle) :Doolean 

E-60 

REGIONS 

EQUALPT 

F- 

(pta, ptb: point) : boolean 

E-68 

POINTS 

EQUALRECT 

F 

(recta,. rectb:rect) : boolean 

E-49 

RECTANGLE 

EOUALRGN 

F 

(rgna, rgnb-.rgnhandle) : boolean 

E-60 

REGIONS 

ERASEARC 

P 

r-.rect; startangle, arcangle: integer 

E-54 

ARC/SECT 

ERASEOVAL 

P 

r:rect 

E-51 

OVALE 

ERASEPOLY 

P 

poly.-polyhandle 

E-67 

POLYGONS 

ERASERECT 

P 

rYrect 

E-50 

RECTANGLE 

ERASERGN 

P 

rgn :r gnhandl e 

E-60 

REGIONS 

ERASEROUNDRECT 

P 

r :rect; ovalwi dth, ovalheight : integer 

E-52 

ROUNDRECT 

FADEDELAY 

F 

billiseconds 

F-07 

SCREEN 

FILLARC 

P 

r : rect; start angle, arcangle: integer; pat. : pattern 

E-55 

ARC/SECT 

FILLOVAL 

P 

r -.rect; pat : pattern 

E-51 

OVALE 
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Ham 

P 

Parametres 

Page 

fiategarie 

FILLPOLY 

P 

poly: polyhandle; pat:pattern 

E-67 

POLYGONS 

FILLRECT 

P 

r.-rect; pat: pattern 

E-50 

RECTANGLE 

FILIRSN 

P 

rgn : rgnhandle ; pat pattern 

E-61 

REGIOf'IS 

FILLROLINDRECT 

P 

r : rect; oveilwidth, ovalheight: integer; pat -.pattern 

E-53 

ROUNDRECT 

FORECOLOR 

P 

color :longint 

E-46 

COLOR 

FRAtEARC 

P 

r : rect ; st art angl e, arcangle: integer 

E-53 

ARC/SECT 

FRftfiECOUNTER 

F 

: frames 

F-06 

SCREEN 

FRAMEOVAL 

P 

r : rect 

E-51 

OVALE 

FRAMEPOLY 

P 

poly: polyhandle 

E-66 

POLYGONS 

FRAMERECT 

P 

r : rect 

E-50 

RECTANGLE 

FRAMERGN 

P 

rgn:rgnhandle 

E-60 

REGIONS 

H3AMEROUNDRECT 

P 

r : rect; ovalwidth, ovalheight integer 

E-51 

ROUNDRECT 

ETCLIP 

P 

rgn:rgnhandle 

E-40 

GRAFPORT 

GETFONTINFO 

P 

info : font info 

E-46 

TEXT 

GETPEN 

P 

V8r pt: point 

E-42 

PEN/LINE 

GETPENST ATE 

P 

ver pnstate : penstate 

E-42 

PEN/LINE 

GETPIXEL 

F 

( h, v : i nt eger ) : bool ean 

E-70 

MISC 

GETPORT 

P 

var gp : graf ptr 

E-37 

GRAFPORT 

GLOBALTOLOCAL 

P 

var pt: point 

E-68 

POINTS 

GRAFDEVICE 

P 

device: integer 

E-38 

GRAFPORT 

HIDECURSOR 

P 


E-41 

CURSOR 

HIDEPEN | 

P 


E-41 

PEN/LINE 

IlNITCURSOR 

P 


E-40 

CURSOR 

IHITGRAF 

P 

globalptr:qdptr (itheport) 

E-35 

GRAFPORT 

INITPORT 

P 

gp : graf ptr 

E-37 

GRAFPORT 

INSETRECT 

P 

var r:rect; dh, dvrinteger 

E-48 

RECTANGLE 

1NSETRGN 

P 

rgn : rgnhandle ; dh, dv : integer 

E-58 

REGIONS 

INVERT ARC 

P 

r : rect; startangle, arcangle integer 

IE-55 

ARC/SECT 

NVERTOVAL 

P 

r : rect 

E-51 

OVALE 

iNVERTPOLY 

P 

poly: polyhandle 

E-67 

POLYGONS 

INVERTRECT 

P 

r:rect 

E-50 

RECT ANGLE 

INVERTRGN 

P 

rgn ; rgnhandle 

E-61 

REGIONS 

INVERTROUNDRECT 

P 

r :rect ; ovalwidth, ovalheight integer 

E-52 

ROUNDRECT 

KEYBDPEEK 

F 

(repeats: boolean; index :keybdqindex; var event: 

F-12 

KEYBOARD 

KEYBDPEEK (bis) 


keyevent) : boolean 

F-12 

KEYBOARD 

KEYBOARD 

F 

:keybdid 

F-10 

KEYBOARD 

KEYISDOWN 

F 

( key: keycap) : boolean 

F-10 

KEYBOARD 

KEYMAP 

P 

var keys : keycapset 

F-10 

KEYBOARD 

KILLPICTURE 

P 

mypicture : pichandle 

E-64 

PICTURES 

KILLPOLY 

P 

poly : polyhandle 

E-65 

POLYGONS 

LEGENDS 

F 

:keybdid 

F-10 

KEYBOARD 

LINE 

P 

dh, dv: integer 

E-43 

PEN/LINE 

LINETO 

P 

h, V: integer 

E-43 

PEN/LINE 

LOCALJOGLOBAL 

P 

var pt : point 

E-68 

POINTS 
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Non 

P 

Parametres 

Page 

Categarie 

MAPPOLY 

P 

poly : polyhandle; srcrect / dstrect :rect 

E-72 

MISC 

MAPPT 

P 

var pt: point; sr erect, dstrect : r ect 

E-71 

MISC 

MAPRECT 

P 

var r : rect; sr erect, dstrect : rect 

E-72 

MISC 

MAPRGN 

P 

rgn rrgnhandle; srcrect, dstrect :rect 

E-72 

MISC 

MICROTIMER 

F 

: microseconds 

F-13 

TIMER 

MOUSELOCATION 

P 

var X: pixels,- var y: pixels 

F-03 

MOUSE 

MOLiSEODOMETER 

F 

:manypixels 

F-04 

MOUSE 

MOUSESCALING 

P 

scale: boolean 

F-04 

MOUSE 

MOUSETRESH 

P 

treshhold: pixels 

F-04 

MOUSE 

MOUSEUPDATES 

P 

delay rmilliseconds 

F-03 

MOUSE 

MOVE 

P 

dh, dv: integer 

E-43 

PEN/LINE 

MOVEPORTTO 

P 

leftglobal, topglobal : integer 

E-38 

GRAFPORT 

OVETO 

P 

h, v: integer 

E-43 

PEN/LINE 

iCWRGN 

F 

rrgnhandle 

E-55 

REGIONS 

NOISE 

P 

wavelength rmicroseconds 

F-07 

SPEAKER 

OBSCURECURSOR 

P 


E-41 

CURSOR 

OFFSETPOLY 

P 

polyrpolyhandle; dh, dv: integer 

E-66 

POLYGONS 

OFFSETRECT 

P 

var r : rect; dh, dv: integer 

E-47 

RECTANGLE 

OFFSETRGN 

P 

rgn -.rgnhandle; dh, dv : integer 

E-58 

REGIONS 

OPENPICTURE 

F 

( pi cf rame : r ect ) : pi chandl e 

E-63 

PICTURES 

OPENPOLY 

F 

: polyhandle 

E-64 

POLYGONS 

OPENPORT 

P 

gp.-grafptr 

E-36 

GRAFPORT 

OPENRGN 

P 


E-57 

REGIONS 

PAINT ARC 

P 

r : rect ; st art angl e, arcangle: integer 

E-53 

ARC/SECT 

PAINTOVAL 

P 

r:rect 

E-51 

OVALE 

PAINTPOLY 

P 

polyrpolyhandle 

E-67 

POLYGONS 

PAINTRECT 

P 

r-.rect 

E-50 

RECTANGLE 

PAINTRGN 

P 

rgn rrgnhandle 

E-60 

REGIONS 

'AINTROUNDRECT 

P 

r:rect; ovalwidth, ovalheight: integer 

E-52 

ROUNDRECT 

PENMODE 

P 

mode: integer 

E-42 

PEN/LINE 

PENNORMAL 

P 


E-43 

PEN/LINE 

PENPAT 

P 

pat: pattern 

E-43 

PEN/LINE 

PENSIZE 

P 

width, height : integer 

E-42 

PEN/LINE 

PICCOMMENT 

P 

i 

kind, datasize: integer,- datahandle : qdhandle 

E-64 

PICTURES 

PORTSIZE 

|p 

width, height: integer 

E-38 

GRAFPORT 

PT2RECT 

p 

pta, ptb: point; var dstrect -.r ect 

E-48 

RECTANGLE 

PTINRECT 

F 

(pt: point; r:rect) : boolean 

E-48 

RECTANGLE 

PTINRGN 

F 

( pt : point; rgn rrgnhandle) : boolean 

E-59 

REGIONS 

PTTOANGLE 

P 

rrrect; pt: point; var angle: integer 

E-49 

RECTANGLE 

RAMPCONTRAST 

P 

contrast : screencontrast 

F-06 

SCREEN 

RANDOM 

F 

: integer 

E-69 

MISC 

RECTINRGN 

F 

(rrrect; rgn rrgnhandle) : boolean 

E-59 

REGIONS 

RECTRGN 

P 

rgn rrgnhandle; rrrect 

E-57 

REGIONS 

REPEATRATE 

P 

var initial rmillisecond; V8r subsequent rmilliseconds 

F-13 

KEYBOARD 
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Nam 

P 

Parametres 

Page 

Categarie 

SCALEPT 

P 

var pt .-point; srcrect, dstrect : rect 

E-70 

MISC 

SCREENSIZE 

P 

var x : pixels; var y:pixels 

F-06 

SCREEN 

SCROLLRECT 

P 

r-.rect; dh, dv : integer; updatergn : rgnhandle 

E-61 

TRANSFERT 

SECTRECT 

F 

(srcrecta, scrrectb:rect ; var dstrect:rect) : boolean 

E-48 

RECTANGLE 

SECTRGN 

P 

srcrgna, srcrgnb, dstrgmrgnhandle 

E-58 

REGIONS 

SETCLIP 

P 

rgn : rgnhandle 

E-39 

GRAFPORT 

SETCONTRAST 

P 

contrast : screencontrast 

F-06 

SCREEN 

SETCURSOR 

P 

crsr : cursor 

E-40 

CURSOR 

SETDATETIME 

P 

dateidatearray 

F-14 

TIME 

SETDIMCONTRAST 

P 

contrast : screencontrast 

F-06 

SCREEN 

SETEMPTYRGN 

P 

rgn : rgnhandle 

E-56 

REGI0f>IS 

SETFADEDELAY 

P 

del ay : mi 1 1 i seconds 

F-07 

SCREEN 

ETLEGENDS 

P 

id:keybdid 

F-10 

KEYBOARD 

SETORIGIN 

P 

h, V: integer 

E-39 

GRAFPORT 

SETPENSTATE 

P 

pnstaterpenstate 

E-42 

PEN/LINE 

SETPORT 

P 

gp : grafptr 

E-37 

GRAFPORT 

SETPORTBITS 

P 

bm:bitmap 

E-38 

GRAFPORT 

SETPT 

P 

var pt: point; h, V: integer 

E-67 

POINTS 

SETRECT 

P 

var r:rect; left, top, right, bottom: integer 

E-47 

RECTANGLE 

SETRECTRGN 

P 

rgn:rgnhandle; left, top, right, bottom: integer 

E-56 

REGIONS 

SETREPEATRATE 

P 

i ni t i al : mi 1 1 i seconds; subsequent : mi 1 1 i seconds 

F-13 

KEYBOARD 

SETSTDPROCS 

P 

var procs : qdprocs 

E-73 

CUSTOM 

SETTIMESTAMP 

P 

time: seconds 

F-14 

TIME 

SETVOLUME 

P 

volune : speakervolume 

F-07 

SPEAKER 

SHOWCURSOR 

P 

i 

E-41 

CURSOR 

SHOWPEN 

P 


E-41 

PEN/LINE 

SILENCE 

P 


F-07 

SPEAKER 

SPACEEXTRA 

P 

extra: integer 

E-45 

TEXT 

'TDARC 

P 

verb:grafverb ; r:rect; startangle, arcengle: integer 

E-74 

CUSTOM 

STDBITS 

P 

var srcbits: bitmap; varsrcrect, dstrect:rect 

E-74 

CUSTOM 

STDBITS (bis) 


mode: integer; rnaskrgmrgnhandle 

E-74 

CUSTOM 

STDCOMMENT 

P 

kind, datasize: integer; datahandle : qdhandle 

E-75 

CUSTOM 

STDGETPIC 

P 

dataptr:qdptr; by tecount integer 

E-75 

CUSTOM 

STDLINE 

P 

newpt: point 

E-74 

CUSTOM 

STDOVAL 

P 

verb : graf verb; r:rect 

E-74 

CUSTOM 

STDPOLY 

P 

verb :graf verb; poly: poly handle 

E-74 

CUSTOM 

STDPUTPIC 

P 

dataptr : qdptr; by tecount : integer 

E-75 

CUSTOM 

STDRECT 

P 

verb : grafverb; r : rect 

E-74 

CUSTOM 

STDRGN 

P 

verb:grafverb; rgn:rgnhandle 

E-74 

CUSTOM 

STDRRECT 

P 

verb: graf verb; r : rect ; ovalwidth, ovalheight: integer 

E-74 

CUSTOM 

STDTEXT 

P 

bytecount, nuner, denom: integer; textbuf: qdptr 

E-73 

CUSTOM 

STDXMEAS 

F 

(bytecount : integer; textbuf : qdptr; var nLmer, 

E-75 

CUSTOM 

STDXMEAS (bis) 


denom: point; var info: font info) integer 

E-75 

CUSTOM 

STRINGWIDTH 

F 

(s:str255) integer 

E-46 

TEXT 
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Nam 

P 

Parametres 

Page 

Categarie 

STUFFHEX 

P 

thingptr :qdptr; s.-str255 

E-70 

MISC 

SUBPT 

P 

srcpt: point; var dstpt: point 

E-67 

POINTS 

TEXTFACE 

P 

face: style 

E -44 

TEXT 

TEXTFONT 

P 

font: integer 

E-44 

TEXT 

TEXTMODE 

P 

mode: integer 

E-44 

TEXT 

TEXTSI2E 

P 

size: integer 

E-44 

TEXT 

TEXTWIDTH 

F 

(textbuf :qdptr; firstbyte, bytecount: integer) integer 

E-46 

TEXT 

TIMER 

F 

billiseconds 

F-14 

TIMER 

TIMESTAMP 

F 

: seconds 

F-14 

TIME 

TIMETODATE 

P 

time: seconds; var date-.datearray 

F-14 

TIME 

UNIONRECT 

P 

srcrecta, scrrectb:rect ; var dstrect:rect 

E-48 

RECTANGLE 

•JNIONRGN 

P 

srcrgna, srcrgnb, dstrgn : rgnhandle 

E-39 

REGIONS 

VOLUME 

F 

: speakervolume 

F-07 

SPEAKER 

jXORRGN 

P 

srcrgna, srcrgnb, dstrgn : rgnhandle 

E-59 

REGIONS 
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Categarie 

P 

Nan 

Parametres 

Page 

ARC/SECT 

P 

ERASE ARC 

r :rect; startangle, arcangle •. integer 

E-54 

ARC/SECT 

P 

FILL ARC' 

r : rect; star tangle, arcangle: integer; pat : pattern 

E-55 

ARC/SECT 

P 

FRAME ARC 

r :rect; start angle, arcangle : integer 

E-53 

ARC/SECT 

P 

INVERT ARC 

r-.rect; startangle, arcangle -.integer 

E-55 

ARC/SECT 

P 

PAINT ARC 

r-.rect; startangle, arcangle: integer 

E-53 

COLOR 

P 

BACKCOLOR 

color :longint 

E-47 

COLOR 

P 

COLORBIT 

wichbit: integer 

E-47 

COLOR 

P 

FORECOLOR 

color :longint 

E-46 

CURSOR 

P 

BUSYDELAY 

del ay : mi 1 1 i seconds 

F-05 

CURSOR 

P 

BUSYIMAGE 

hotx: pixels; hoty: pixels; height : cur sorheight; 

F-05 

CURSOR 


BUSYIMAGE (bis) 

data: cur sorptr; mask : cursorptr 

F-05 

CURSOR 

P 

CURSORIMAGE 

hot x. : pi x el s; hoty : pi x el S; hei ght : cur sorhei ght ; 

F-05 

CURSOR 


CURSORIMAGE (bis) 

proceduredat a: cursorptr; mask : cursorptr 

F-05 

CURSOR 

P 

CURSORTRACKING 

track: boolean 

F-05 

CURSOR 

P 

HIDECURSOR 


E-41 

CURSOR 

P 

INITCURSOR 


E-40 

CURSOR 

P 

OBSCURECURSOR 

r- 

E-41 

CURSOR 

P 

SETCURSOR 

crsr : cursor 

E-40 

CURSOR 

P 

SHOWCURSOR 


E-41 

CUSTOM 

P 

SETSTDPROCS 

var procs qdprocs 

E-73 

CUSTOM 

P 

STD ARC 

verb : grafverb; r:rect; startangle, arcangle integer 

E-74 

CUSTOM 

P 

STDBITS 

var srcbits: bitmap: varsrcrect. dstrect:rect 

E-74 

CUSTOM 


STDBITS (bis) 

mode: integer,- maskrgn:rgnhandle 

E-74 

CUSTOM 

P 

STDCOMMENT 

kind, datasize: integer; datahandleiqdhandle 

E-75 

CUSTOM 

P 

STDGETPIC 

dataptr : qdptr,- bytecount : integer 

E-75 

CUSTOM 

P 

STDLINE 

newpt: point 

E-74 

CUSTOM 

P 

STDOVAL 

verb : grafverb; r : rect 

E-74 

CUSTOM 

P 

STDPOLY 

verb : grafverb; poly -.poly handle 

E-74 

CUSTOM 

P 

STDPUTPIC 

dataptr: qdptr; bytecount: integer 

E-75 

CUSTOM 

P 

STDRECT 

verb : grafverb; r : rect 

E-74 

CUSTOM 

P 

STDRGN 

verb : grafverb; rgn : rgnhandle 

E-74 

CUSTOM 

P 

STDRRECT 

verb : grafverb; r : rect; ovalwidth, ovalheight-. integer 

E-74 

CUSTOM 

P 

STDTEXT 

bytecount, numer, denom : integer; textbuf : qdptr 

E-73 

CUSTOM 

F 

STDXMEAS 

(bvtecount:inteaer: textbuf :adDtr: var numer. 

E-75 

CUSTOM 


STDXMEAS (bis) 

denom : point; var info :fontinfo) : integer 

E-75 

GRAFPORT 

P 

BACKPAT 

pat: pattern 

E-40 

GRAFPORT 

P 

CLIPRECT 

r:rect 

E-40 

GRAFPORT 

p ! 

CLOSEPORT 

gp : graf ptr 

E-37 

GRAFPORT 

p 

GETCLIP 

rgn:rgnhandle 

E-40 

GRAFPORT 

p 

GETPORT 

var gp: graf ptr 

E-37 

GRAFPORT 

p 

GRAFDEVICE 

device: integer 

E-38 

GRAFPORT 

p 

INITGRAF 

global ptr: qdptr (itheport) 

E-35 

GRAFPORT 

p 

INITPORT 

gp : graf ptr 

E-37 

GRAFPORT 

p 

MOVEPQRTTO 

leftglobal, topglobal integer 

E-38 
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Categarie 

P 

Nan 

Parametres 

Page 

GRAFPORT 

P 

OPENPORT 

gp : graf ptr 

E-36 

GRAFPORT 

P 

PORTSIZE 

width, height : integer 

E-38 

GRAFPORT 

P 

SETCLIP 

rgn:rgnhandle 

E-39 

GRAFPORT 

P 

SETORIGIN 

h, v: integer 

E-39 

GRAFPORT 

P 

SETPORT 

gp : graf ptr 

E-37 

GRAFPORT 

P 

SETPORTBITS 

bm: bitmap 

E-38 

KEYBOARD 

F 

KEYBDPEEK 

(repeats: boolean; index: key bdqindex; var event: 

F-12 

KEYBOARD 

KEYBOARD 

F 

KEYBDPEEK (bis) 
KEYBOARD 

WoSoa, oar . h~~»4 t*- 

:keybdid 

F-10 

KEYBOARD 

F 

KEYISDOWN 

( key : keycap ) : boolean 

F-10 

KEYBOARD 

P 

KEYMAP 

var keys : keycapset 

F-10 

KEYBOARD 

F 

LEGENDS 

:keybdid 

F-10 

KEYBOARD 

P 

REPEATRATE 

var initial:milli second; var subsequent : mi 1 1 i seconds 

F-13 

KEYBOARD 

P 

SETLEGENDS 

id:keybdid 

F-10 

KEYBOARD 

P 

SETREPEATRATE 

i ni t i al : mi 1 li seconds; subsequent : mi 1 1 i seconds 

F-13 

MISC 

F 

GETPIXEL 

( h, v : i nt eger ) : bool ean 

E-70 

MISC 

P 

MAPPOLY 

poly : poly handle; sr erect, dstrect :rect 

E-72 

MISC 

P 

MAPPT 

var pt: point; sr erect, dstrect : rect 

E-71 

MISC 

P 

MAPRECT 

var r : rect ; sr erect, dstrect :rect 

E-72 

MISC 

P 

MAPRGN 

rgmrgnhandle; sr erect, dstrect : rect 

E-72 

MISC 


RANDOM 

: integer 

E-69 

MISC 


SCALEPT 

var pt: point; srcrect, dstrect : rect 

E-70 

MISC 


STUFFHEX 

thingptr:qdptr ; S:str255 

E-70 

MOUSE 

P 

MOUSELOCATION 

var x: pixels; var y : pixels 

F-03 

MOUSE 

F 

MOUSEODOMETER 

:manypixels 

F-04 


P 

MOUSESCALING / 
MOUSETRESH 

scale: boolean 

F-04 

MOUSE 


treshhold: pixels 

F-04 

MOUSE 


MOUSEUPDATES # 

delay billiseconds 

F-03 

OVALE 

P 

ERASEOVAL 

r:rect 

E-51 

OVALE 

P 

FILLOVAL 

r : rect ; pat pattern 

E-51 

OVALE 

P 

FRAMEOVAL 

r:rect 

E-51 

OVALE 

P 

INVERTOVAL 

r : rect 

IE-51 

OVALE 

P 

PAINTOVAL 

r : rect 

E-51 

PEN/LINE 

P 

GETPEN 

var pt: point 

E-42 

PEN/LINE 

P 

GETPENSTATE 

var pnstate:penstate 

E-42 

PEN/LINE 

P 

HIDEPEN 


E-41 

PEN/LINE 

P 

LINE 

dh, dv: integer 

E-43 

PEN/LINE 

P 

LINETO 

h, V: integer 

E-43 

PEN/LINE 

P 

MOVE 

dh, dv: integer 

E-43 

PEN/LINE 

P 

MOVETO 

h, V: integer 

E-43 

PEN/LINE 

P 

PENMODE 

mode: integer 

E-42 

PEN/LINE 

P 

PENNORMAL 


E-43 

PEN/LINE 

P 

PENPAT 

pat: pattern 

E-43 

PENAINE 

P 

PENSIZE 

width, height: integer 
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pnstate:penstate 
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P 
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PICTURES 

P 

CLOSEPICTURE 


E-64 

PICTURES 

P 

DRAWPICTURE 

my pi ct ur e pi chandl e; dstrect : r ect 

E-64 

PICTURES 

P 

KILLPICTURE 

mypicture : pichandle 

E-64 

PICTURES 

F 

OPENPICTURE 

( pi cf r ame : r ect ) : pi chandl e 

E-63 

PICTURES 

P 

PICCOMMENT 

kind, datasize : integer; datahandle : qdhandle 

E-64 

POINTS 

P 

ADOPT 

srcpt: point; var dstpt -.point 

E-67 

POINTS 

F 

EQUALPT 

(pta, ptb: point ): boolean 

E-68 

POINTS 

P 

GLOBALTOLOCAL 

var pt: point 

E-68 

POINTS 

P 

LOCALTOGLOBAL 

var ptrpoint 

E-68 

POINTS 

P 

SETPT 

var ptrpoint; h,v: integer 

E-67 

POINTS 

P 

SUBPT 

srcpt: point; var dstpt: point 

E-67 
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P 

CLOSEPOLY 


E-65 

POLYGONS 

P 

ERASEPOLY 

poly: poly handle 

E-67 

POLYGONS 

P 

FILLPOLY 

poly : polyhandle; pat : pattern 

E-67 
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P 

FRAMEPOLY 

poly: polyhandle 

E-66 

POLYGONS 

P 

INVERTPOLY 

poly: poly handle 

E-67 

POLYGONS 

P 

KILLPOLY 

poly: poly handle 

E-65 

POLYGONS 

P 

OFFSETPOLY 

poly polyhandle; dh, dv : integer 

E-66 

POLYGONS 

F 

OPENPOLY 

: polyhandle 

E-64 

POLYGONS 

P 

PAINTPOLY 

poly-.polyhandle 
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F 

EMPTYRECT 

(r-.rect) -.boolean 
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F 

EOUALRECT 
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P 
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P 

FILLRECT 
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P 
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P 
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pta, ptb: point; var dstrect:rect 
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F 

PTINRECT 
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E-48 

RECTANGLE 

P 

PTTOANGLE 

r:rect; ptrpoint; var angle: integer 

E-49 

RECTANGLE 

F 

SECTRECT 

(srcrecta, scrrectb:rect; var dstrect -.r ect ): boolean 

E-48 

RECTANGLE 

P 

SETRECT 
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E-47 

RECTANGLE 

P 

UNIONRECT 

srcrecta, scrrectb:rect; var dstrect :rect 
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P 

CLOSERGN 
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REGIONS 

P 

COPYRGN 

srcrgn, dstrgnrrgnhandle 

E-56 

REGIONS 

P 

DIFFRGN 

srcrgna, srcrgnb, dstrgnrrgnhandle 

E-59 

REGIONS 

P 

DISPOSERGN 

rgn :r gnhandl e 

E-56 

REGIONS 

F 

EMPTYRGN 

(rgn : rgnhandle):boolean 
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P 
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Parametres f 

FILLRGN 

rgn:rgnhandle; pat pattern 

FRAMERGN 

rgn : rgnhandle 

INSETRGN 

rgn:rgnhandle ; dh, dv : integer 

INVERTRGN 

rgn:rgnhandle 

NEWRGN 

:rgnhandle 

OFFSETRGN 

rgmrgnhandle; dh, dv: integer 

OPENRGN 


PAINTRGN 

rgn:rgnhandle 

PTINRGN 

( pt : point; rgn irgnhandle) : boolean 

RECTINRGN 

(r:rect; rgn : rgnhandle) -boolean 

RECTRGN 

rgn : rgnhandle ; r:rect 

SECTRGN 

srcrgna, srcrgnb, dstrgn:rgnhandle 

SETEMPTYRGN 

rgn:rgnhandle 

SETRECTRGN 

rgn :rgnhandle; left, top, right, bottom integer 

UNIONRGN 

srcrgna, srcrgnb, dstrgn:rgnhandle 

XORRGN 

srcrgna, srcrgnb, dstrgn:rgnhandle 

ERASEROUNDRECT 

r:rect; ovalwidth, ovalheight integer 

FILLROUNDRECT 

r:rect; oval width, oval height integer; pat pattern 

FRAMEROUNDRECT 

r:rect; ovalwidth, ovalheight: integer 

I N VERTROUNDRECT 

r:rect; ovalwidth, ovalheight: integer 

PAINTROUNDRECT 

r:rect; ovalwidth, ovalheight: integer 
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: screencontrast 
: screencontrast 
: milliseconds 
: frames 

contrast : screencontrast 
var x:pixels; var y:pixels 
contrast : screencontrast 
contrast : screencontrast 

delay: milliseconds F— 07 

wavelength: microseconds; duration : mi Hi seconds F-07 

wavelength microseconds F-07 

vol ume : speakervol ume F-07 

F-07 

: speakervol ume F-07 

(ch:char):integer E-45 

ch:char E-45 

s : str255 E-45 

textbuf : qdptr ; firstbyte, by tecount integer E-45 

infO:fontinfo E-46 

extra: integer E-45 

(s:str255) : integer E-46 

face: style E -44 

font: integer E-44 
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ABSTRACT 

The Scrap Manager is a set of simple routines and data types that help 
Macintosh applications manipulate the Clipboard for cutting and pasting 
between applications, desk accessories, or an application and a desk 
accessory. This manual describes the Scrap Manager in detail. 


Erratum: 

The 'TEXT' type of data in the desk scrap is simply a series of ASCII 
characters, without a character count or an optional comment* If you 
want to know the count, you can get it by passing a NIL handle to the 
GetScrap function* 
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ABOUT THIS MANUAL 

This manual describes the Scrap Manager, a new part of the Macintosh 
User Interface Toolbox in ROM version 7. *** Eventually it will become 

part of a comprehensive manual describing the entire Toolbox. *** The 
Scrap Manager supports cutting and pasting between applications, desk 
accessories, or an application and a desk accessory. 

Like all documentation about Toolbox units, this manual assumes you're 
familiar with the Macintosh User Interface Guidelines, Lisa Pascal, and 
the Macintosh Operating System's Memory Manager. You should also be 
familiar with the following: 

- QuickDraw pictures 

- Resources , as discussed in the Resource Manager manual 

- The Toolbox Event Manager 

This manual is intended to serve the needs of both Pascal and 
assembly-language programmers. Information of interest only to 
assembly-language programmers is isolated and labeled so that Pascal 
programmers can conveniently skip it. 

The manual begins with an introduction to the Scrap Manager, an 
overview of the scrap that you manipulate with it, and a discussion of 
the types of data that the scrap may contain. 

Next, a section on using the Scrap Manager introduces its routines and 
tells how they fit into the flow of your application. This is followed 
by detailed descriptions of all Scrap Manager routines , their 
parameters, calling protocol, effects, side effects, and so on. 

Following these descriptions is a section' that gives the exact format 
of the scrap, for those programmers who are interested; you don't have 
to read this section to be able to use the Scrap Manager routines. 

Finally, there's a summary of the Scrap Manager, for quick reference, 
followed by a glossary of terms used in this manual. 


ABOUT THE SCRAP MANAGER 

The Scrap Manager is a set of simple routines and data types that help 
Macintosh applications manipulate the desk scrap , which is where data 
that's cut (or copied) and pasted between applications is stored. An 
application can also use the desk scrap for storing data that's cut and 
pasted within the application, but usually it will have its own private 
scrap for this purpose. The format of the private scrap may be 
whatever the application likes, since no other application will use it. 
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From the user's point of view, there's a single place where all cut or 
copied data resides, and it's called the Clipboard. The Cut command 
deletes data from a document and places it in the Clipboard; the Copy 
command copies data into the Clipboard without deleting it from the 
document. The next Paste command— whether applied to the same document 
or another, in the same application or another — inserts the contents of 
the Clipboard at a specified place. An application that offers these 
editing commands will usually also have a special window for displaying 
the current Clipboard contents; it may show the Clipboard window at al-1 
times or only when requested (via the Show Clipboard and Hide Clipboard 
commands). 

The desk scrap is the vehicle for transferring data not only between 
two applications but also between an application and a desk accessory, 
or even between two desk accessories. Desk accessories that display 
text will commonly allow the text to be cut or copied. The user might, 
for example, use the Calculator accessory to do a calculation and then 
copy the result into a document. It's also possible for a desk 
accessory to allow something to be pasted into it. 

( hand ) 

The Scrap Manager is optimized for transferring small 
amounts of data; attempts to transfer very large amounts 
of data may fail due to lack of memory. 

The nature of the data to be transferred varies according to the 
application. For example, for the Calculator or a word processor the 
data is text, and for a graphics application it's a picture. The 
amount of information retained about the data that's transferred also 
varies. Between two text applications, text can be cut and pasted 
without any loss of information; however, if the user of a graphics 
application cuts a picture consisting of text and then pastes it into a 
document created with a word processor, the text in the picture may not 
be editable in the word processor, or it may be editable but not look 
exactly the same as in the graphics application. The Scrap Manager 
allows for a variety of data types and provides a mechanism whereby 
applications have control over how much information is retained when 
data is transferred. 

Like any scrap, the desk scrap can be kept on the disk (in the scrap 
file ) if there's not enough room for it in memory. It may remain on 
the disk throughout the use of the application but must be read back 
into memory when the application terminates , since the user may then 
remove that disk and insert another. The Scrap Manager provides 
routines for writing the desk scrap to the disk and for reading it back 
into memory. 


OVERVIEW OF THE DESK SCRAP 


The desk scrap is initially located in the application heap, with a 
handle to it in low memory. When starting up an application, the 
Segment Loader temporarily moves the scrap out of the heap into the 
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stack, reinitializes the heap, and puts the scrap back in the heap. 

(See Figure 1.) For a short time while it does this, two copies of the 
scrap exist in the memory allocated for the stack and the heap; for 
this reason, the desk scrap cannot be bigger than half that amount of 
memory. 


Initially; 


low 

memory 


old 

heap 


* - Kv.%v.*.v.v,v.v.v.*.i 

I • • • • ........a.... J 


gzclesk scrap £3 




Them 



f:reet of stack*! 


I I 



Finally: 



new 

heap 


Figure 1 . The Desk Scrap at Application Start-up 


The application can get the size of the desk scrap by calling a Scrap 
Manager function named Info Scrap. An application concerned about 
whether there's room for the desk scrap in memory might be set up so 
that a small initial segment of the application is loaded in just to 
check out the scrap size. After a decision is made about whether to 
keep the scrap in memory or on the disk, the remaining segments can be 
loaded in as needed. 


There are certain disadvantages to keeping the desk scrap on the disk. 
The disk may be write-protected, may not have enough room for the 
scrap, or may be removed during use of the application. If the 
application can't write the scrap to the disk, it should put up an 
alert box informing the user, who may want to abort the application at 
that point. 


The application must use the desk scrap for any Paste command given 
before the first Cut or Copy command (that is, the first since the 
application started up or since a desk accessory was deactivated); this 
requires copying the desk scrap to the private scrap, if any. Clearly 
the application must keep the contents of the desk scrap intact until 
the first Cut or Copy command is given. Thereafter it can ignore the 
desk scrap until a desk accessory is activated or the application is 
terminated; in either of these cases, it must copy its private scrap to 
the desk scrap. Thus whatever was last cut or copied within the 
application will be pasted if a Paste command is then given in a desk 
accessory or in the next application. 
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1. User enter® word pro cess or after cutting a picture in the previous application. 


empty 

private scrap 

2. User gives Paste command in word p r o ce sso r (without a previous Cut or Copy). 


picture 


desk scrap 


picture 


converted 

picture 


4 pasted where specified 


desk scrap 


private scrap 


3a. User cuts text in word pr ocesso r. 


picture 


text 


desk scrap private scrap 

3b. User leaves word pr ocessor . 



desk scrap 


private scrap 


OR: 


3. User leaves word processor 
(without a previous Cut or Copy). 


picture 


converted 

picture 


desk scrap 


private scrap 


Figure 2. Interaction between Scraps 

Figure 2 illustrates how the interaction between the desk scrap and the 
application's private scrap might occur when the user gives a Paste 
command in a word processor after cutting a picture in a graphics 
application. As the picture that was cut gets copied to the private 
scrap, it's converted to the format of that scrap. If the user leaves 
the word processor after cutting or copying text, the text first goes 
into the private scrap and then gets copied to the desk scrap. On the 
other hand, if the user never gives a Cut or Copy command, the 
application won't copy the private scrap to the desk scrap, so the 
original contents of the desk scrap will be retained. 


Suppose the word processor in Figure 2 displays the contents of the 
Clipboard. Normally it will display its private scrap; however, to 
show the Clipboard contents at any time before step 2, it will have to 
display the desk scrap instead, or first copy the desk scrap to its 
private scrap. It can instead simply copy the desk scrap to its 
private scrap at start-up (step 1), so that showing the Clipboard 
contents will always mean displaying the private scrap. 


A similar scheme to that shown in Figure 2 must be followed when the 
user reenters an application after using a desk accesory, since the 
user may have done cutting or copying in the accessory. The 
application can in fact check whether any such cutting or copying was 
done, by looking at a count that's returned by InfoScrap. If this 
count changes during use of the desk accessory, it means the contents 
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of the desk scrap have changed; Che applicacion will have Co copy Che 
desk scr'sp Co Che privaCe scrap, if any, and updaCe the concencs of Che 
Clipboard window, if chere is one and if it's visible. If the count 
returned by InfoScrap hasn't changed, however, the application won't 
have to take either of these actions. 

If the application encounters problems in trying to copy one scrap to 
another, it should alert the user. The desk scrap may be too large to 
copy to the private scrap , in which case the user may want to leave the 
application or just proceed wich an empty Clipboard. If the private 
scrap is too large to copy to the desk scrap, either because it's 
disk-based and too large to copy into memory or because it exceeds the 
max -i imim size allowed for the desk scrap, the user may want to stay in 
the application and cut or copy something smaller. 


DESK SCRAP DATA TYPES 

From the user's point of view there can be only one thing in the 
Clipboard at a time, but internally there may be more than one data 
item in the desk scrap, each representing the same Clipboard contents 
in a different form. For example, text cut with a word processor may 
be stored in the desk scrap both as text and as a QuickDraw picture. 

Desk scrap data types are like resource types. As defined in the 
Resource Manager, their Pascal type is as follows: 

TYPE ResType - PACKED ARRAY [1..4] OF CHAR; 

The Scrap Manager recognizes two standard types of data in the desk 
scrap. 


- ’TEXT': a series of ASCII characters, preceded by a long word 
containing the number of characters and optionally followed by a 
comment, as described below. 

— 'PICT*: a QuickDraw picture, which is a saved sequence of drawing 
commands that can be played back with the DrawPlcture command and 
ma y include picture comments. (See the QuickDraw manual for- 
details.) 

Applications must write at least one of these standard types of data to 
the desk scrap and must be able to read both types. Most applications 
will prefer one of these types over the other; for example, a word 
processor prefers text while a graphics application prefers pictures. 

An application should at least write its preferred standard type of 
data to the desk scrap, and ideally will write both types (to pass the 
most information possible on to the receiving application, which may 
prefer the other type). 

An application reading the desk scrap will look for its preferred data 
type. If its preferred type isn't there, or if it's there but was 
written by an application having a different preferred type, some 
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information may be lost in the transfer process. For example, consider 
the user 'of a graphics application who cuts a picture consisting of 
text and then goes into a word processor and pastes it (as illustrated 
in Figure 3). 

— If the graphics application writes only its preferred data type, 
picture, to the desk scrap (like application A in Figure 3), the 
text in the picture will not be editable in the word processor, 
because it will be seen as just a series of drawing commands and 
not a sequence of characters* 

- On the other hand, if the graphics application takes the trouble 
of recognizing which characters have been drawn in the picture, 
and also writes them out to the desk scrap as text (like 
application B in Figure 3), the word processor will be able to 
treat them like any text, with editing or whatever. In this case, 
however, any part of the picture that isn't text will be lost. 


Graphics Application A 


picture 
consisting 
of text 



Word Pr o cessor 


picture 
^ consisting 
of text 


Graphics Application B Word Processor 



Figure 3. Inter-Application Cutting and Pasting 

In addition to the two standard data types, the desk scrap may also 
contain application— specific types of data. If several applications 
are to support the transfer of a private type of data, each one will 
write and read that type — clearly its preferred type — but still must 
write at least one of the standard types and be able to read both 
standard types. 

(eye) 

There should never be more than one of each type of data 
in the desk scrap at a time. 

The order in which data is written to the desk scrap is important: the 
application should write out the different types in order of 
preference. For example, if it's a word processor that writes out a 
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private type of data as well as text and pictures, it should do so in 
that orddr. 

Since the size of the desk scrap is limited, it may be too costly to 
write out both an application— specific type of data and one (or both) 
of the standard types* If so, the comments that can accompany text or 
pictures might be useful. Instead of creating an application-specific 
data type, you may be able to encode additional information in these 
comments. For example, instead of having a data type that consists of 
text and formatting information combined in an application— specific 
way, you can encode the formatting information in the text comment. 
Applications that are to process that information can do so, while 
others can ignore it. 

A text comment follows the last character in the text and must begin 
with the application ID , a four— character sequence that you choose to 
uniquely identify your application when you build it. *** (This ID 
will be discussed further in a future revision of the manual "Putting 
Together a Macintosh Application". ) *** Any data that you like can - 

follow the application ID. 

As described in the QuickDraw manual, picture comments may be stored in 
the definition of a picture with the QuickDraw procedure PicComment . 

The DrawPicture procedure passes any such comments to a special routine 
set up by the application for that purpose. 


USING THE SCRAP MANAGER 


This section discusses how the Scrap Manager routines fit into the 
general flow of an application program and gives you an idea of which 
ones you'll need to use. The routines themselves are described in 
detail in the next section. 

The application should Inquire as early as possible about the size of 
the desk scrap to determine whether there will be enough room for 
itself and the scrap to coexist in the heap; it can do so by calling 
the InfoScrap function. If there won't be enough room for the desk 
scrap in the heap, the application should call the UnloadScrap 
procedure to write the scrap from memory onto the disk. InfoScrap also 
provides a handle to the desk scrap if it's in memory, its file name on 
the disk, and a count that's useful for testing whether the contents of 
the desk scrap have changed during the use of a desk accessory. 

If a Paste command is given before the first Cut or Copy command after 
the , application starts up, the application must copy the contents of 
the desk scrap to its private scrap, if any. It can do this either 
upon starting up or when the Paste command that needs to use the desk 
scrap is given. The latter method usually suffices, but applications 
that support display of the Clipboard will benefit from copying the 
desk scrap at 8tart--up. The Scrap Manager routine that gets data from 
the desk scrap is called GetScrap. 
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When the user gives a command that terminates the application, the 
application's private scrap will usually have to be copied to the desk 
scrap* If the desk scrap is on the disk, it must first be read into 
memory with the LoadScrap function. The application must call 
ZeroScrap to reinitialize the desk scrap and clear its previous 
contents, and then Put Scrap to put data in the scrap. 

(eye) 

Do not copy the private 3 crap to the desk scrap unless a 

Cut or Copy command was given that changed the contents 

of the Clipboard. 

The same kind of scrap interaction that occurs at application start-up 
also applies to returning to the application from a desk accessory 
(that is, an activate event that activates an application window after 
deactivating a system window). Similarly, the interaction when an 
application terminates also applies to accessing a desk accessory from 
the application (as reported by an activate event that deactivates an 
application window and activates a system window). Note, howeverv, that 
a desk accessory shouldn't concern itself with writing or reading the 
desk scrap from the disk. 

Cutting and pasting between two desk accessories follows an analogous 
scenario. As described in the Desk Manager manual, the way a desk 
accessory learns it must respond to an editing command is that its 
control routine receives a message telling it to perform the command, 
the application needs to call the Desk Manager function SystemEdit to 
make this happen. 


SCRAP MANAGER ROUTINES 

This section describes all the Scrap Manager routines. They are 
presented in their Pascal form; for information on using them from 
assembly language, se6 "Using the Toolbox from Assembly Language" *** 
for now, see "Using QuickDraw from Assembly Language" in the QuickDraw 

manual ***• 


Getting Scrap Information 


FUNCTION InfoScrap : PScrapStuff; 


InfoScrap returns a pointer to information about the desk scrap. The 
PScrapStuff data type is defined as follows: 
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TYPE PScrapStuff 
ScrapStuff 


“ScrapStuf f ; 

RECORD 

scrapSize: Longlnt; 

scrapHandle: Handle; 
sccapCount: INTEGER; 
scrapStace: INTEGER; 
scrapName: StrlngPtr 

END; 


ScrapSize Is the size of the entire desk scrap in bytes. ScrapHandle 
Is a handle to the scrap if it's in memory, or NIL if not. ScrapCount 
is a count that changes every time ZeroScrap is called and is useful 
for testing whether the contents of the desk scrap have changed during 
the use of a desk accessory (see ZeroScrap under "Writing to the 
Scrap", below). ScrapState is positive if the desk scrap is in memory 
or 0 if it's on the disk. ScrapName is a pointer to the name of the 
scrap file, usually DeskScrap. 


Keeping the Scrap on the Disk 


FUNCTION UnloadScrap : Longlnt; 

UnloadScrap writes the desk scrap from memory to the scrap file. If 
the desk scrap is already on the disk, it does nothing. If no error 
occurs, UnloadScrap returns 0; otherwise, it returns an appropriate 
Operating System error code. 


Assembly-language note : The macro you invoke to call 
UnloadScrap from assembly language is named _UnlodeScrap. 


FUNCTION Load Scrap : Longlnt; 

LoadScrap reads the desk scrap from the scrap file into memory. If the 
desk scrap is already in memory, it does nothing. If no error occurs, 
LoadScrap returns 0; otherwise, it returns an appropriate Operating 
System error code. 


As sembly-language note : The macro you invoke to call LoadScrap 
from assembly language is named _LodeScrap. 
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Reading from the Scrap 


FUNCTION GetScrap (hDest: Handle; theType: ResType; VAR offset: 

Longlnt) : Longlnt; 

GetScrap reads the data of type theType from the desk scrap (whether in 
memory or on the disk), makes a copy of it in memory, and sets up the 
hDest handle to point to the copy. Usually you’ll pass an empty handle 
in hDest. In the offset parameter, GetScrap returns the location of 
the data as an offset (in bytes) from the beginning of the desk scrap. 
If no error occurs, the function result is the length of the data in 
bytes; otherwise, it's either an appropriate Operating System error 
code (which will be negative) or the following predefined constant: 

CONST noTypeErr =« -102; {there's no data of the requested type} 
For example, given an empty handle declared as ' 

VAR pHndl : PicHandle 
you can make the following calls: 

GetScrap ( POINTER( ORD( pHndl ) ) , ’ PICT ’ ) ; 

DrawPicture(pHndl) ; 

Your application should pass its preferred data type to GetScrap. If 
it doesn't prefer one data type over any other, it should try getting 
different types until the offset returned is 0. An offset of 0 means 
that data was the first to be written out and so should be the 
preferred type of the application that wrote it. 

If you pass NIL in hDest, GetScrap will not read in the data. This is 
useful If you want to be sure the data is there before allocating space 
for its handle, or if you just want to know the size of the data. If 
there isn't enough room in memory for a copy of the data, as may be the 
case for a complicated picture, you can customize QuickDraw's picture 
retrieval so that DrawPicture will read from the picture directly from 
the scrap file. (QuickDraw also lets you customize how pictures are 
saved so you can save them in a file; see the QuickDraw manual for 
details about customizing.) 


Writing to the Scrap 


FUNCTION ZeroScrap : Longlnt; 

ZeroScrap initializes the desk scrap, clearing its contents; you must 
call it before the first time you call PutScrap (described below). If 
no error occurs, ZeroScrap returns 0; otherwise, it returns an 
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appropriate Operating System error code* 

ZeroScrap also changes the scrapCount field of the record of 
Information provided by InfoScrap. This Is useful for testing whether 
the contents of the desk scrap have changed during the use of a desk 
accessory* The application can save the value of the scrapCount field 
when one of Its windows Is deactivated and a system window Is 
activated. Then, each time through Its event loop. It can check to see 
whether the value of the field has changed. If so. It means the desk 
accessory called ZeroScrap (and, presumably, PutScrap) and thus changed 
the contents of the desk scrap. 


FUNCTION PutScrap (length: Longlnt; the Type: ResType; source: Ptr) : 
Longlnt ; 

PutScrap writes the data pointed to by the source parameter to the desk 
scrap (whether In memory or on the disk). The length parameter 
Indicates the number of bytes to write, and theType Is the data type 
(which should be different fro# the type of any data already In the 
desk scrap). If no error occurs, the function redult is 0; otherwise, 
it's an appropriate Operating System error code. 

(eye) 

Don't forget to call ZeroScrap (above) to clear the scrap 
before your first call to PutScrap. 


FORMAT OF THE DESK SCRAP 


In general, the desk scrap consists of a series of data items that have 
the following format: 


Number of bytes 
4 bytes 
4 bytes 
n bytes 


Contents 

Type (a sequence of four characters) 
Length of following data in bytes 
Data; n must be even (if the above length 
is odd, include an extra byte) 


The standard types are 'TEXT' and 'PICT'. You may use any other 
four-character sequence for types specific to your application. 


The format of the data for the 'TEXT' type is as follows: 


Number of bytes 
4 bytes 
n bytes 
m bytes 


Contents 

Number of characters in the text 
The characters in the text 
Optional comment: the 4-byte application 
ID followed by any information desired 


The data for the 'PICT* type is a QuickDraw picture, which consists of 
the size of the picture in bytes, the picture frame, and the picture 
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definition data (which may include picture comments). See the 
QuickDraw manual for details. 
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SUMMARY OF THE SCRAP MANAGER 


Constants 



CONST noTypeErr - * 

-102; {there's 

no data of the requested type} 

Data Structures 

TYPE PScrapStuff - 

■*ScrapStuf f ; 


Scrap Stuff ■ 

RECORD 



scrapSize : 

Longlnt ; 


scrapHandle : 

Handle ; 


scrapCount : 

INTEGER; 


scrapState : 

INTEGER; 


scrapName : 

String Ptr 


END; 

v. 

Routines 




Getting Scrap Information 
FUNCTION InfoScrap : PScrapStuff;. 


Keeping the Scrap on the Disk 

FUNCTION UnloadScrap : Long In t; 
FUNCTION LoadScrap : Long In t; 


Reading from the Scrap 

FUNCTION GetScrap (hDest: Handle; theType: Res Type; VAR offset: Longlnt) 

: Longlnt; 


Writing to the Scrap 
FUNCTION ZeroScrap : Longlnt; 

FUNCTION PutScrap (length: Longlnt; theType: ResType; source: Ptr) : 

Longlnt; 
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Asaemblv-Language Information 


Constants 


noTypeErr 


.EQU -102 


; there 's no data of the requested type 


Scrap Information Data Structure 


scrapSize 

scrapHandle 
scrapCount 
scrapState 
scrap Name 


Size of desk scrap in bytes *** (currently named 
scrap Info) *** 

Handle to desk scrap in memory 
Count changed by Zero Scrap 

Positive if desk scrap in memory , 0 if on disk 
Pointer to name of scrap file 



Special Macro Names 

Routine name Macro name 

Load Scrap _Lode Scrap 

UnloadScrap JUnlodeScrap 
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GLOSSARY 

application ID: A four-character sequence that you choose to identify 
your application when you you build It. 

desk scrap: The place in memory or on the disk where data that's cut 
(or copied) and pasted between applications is stored. 

scrap file: The file containing the desk scrap. 
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COMMENTS? 

Macintosh User Education encourages your comments on this manual. 

- What do you like or dislike about it? 

- Were you able to find the information you needed? 

- Was it complete and accurate? 

- Do you have any suggestions for improvement? 

Please send your comments to the author (indicated on the cover 
page) at 10460 Bandley Drive M/S 3-G, Cupertino CA 95014. 

Mark up a copy of the manual or note your remarks separately. 

(We'll return your marked-up copy if you like.) 

Thanks for your helpl 
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ABSTRACT 

The TextEdit package of the Macintosh User Interface Toolbox is a set of 
data types and routines for handling basic text formatting and editing 
capabilities in a Macintosh application* This manual describes TextEdit 
in detail. 
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ABOUT THIS MANUAL 


The TextEdit package of the Macintosh User Interface Toolbox is a set 
of data types and routines for handling basic text formatting and 
editing capabilities in a Macintosh application. This manual describes 
TextEdit in detail. 

The Toolbox also includes a more sophisticated text editing package, 
called CoreEdit* You'll need to use CoreEdit instead of TextEdit if 
you want fully justified text, recognition of word boundaries during 
editing ("Intelligent cut and paste"), or tabbing. Bear in mind, 
however, that CoreEdit is not in the Macintosh ROM, and occupies over 
6K of your application's available memory instead. 

(hand) 

This manual describes the TextEdit that works with 
version 7 of the ROM. If you're using a different 
version, the information presented here may not apply. 

Like all documentation about Toolbox units, this manual assumes you're 
familiar with the Macintosh User Interface Guidelines, Lisa Pascal, and 
the Macintosh Operating System's Memory Manager. You should also be 
familiar with the following: 

- The basic concepts and structures behind QuickDraw, particularly 
points, rectangles, graf Ports, fonts, and character style. 

- The ToolBox Event Manager. Some TextEdit routines are called only 
in response to particular events. 

- The Window Manager, particularly update and activate events. 

The manual begins with an introduction to TextEdit and what you can do 
with it. It then discusses the edit record, the primary data structure 
used by the text editing routines. Learning about this data structure 
will give you the background you need to understand the routines 
themselves. 

Next, a section on using TextEdit introduces you to its routines and 
tells how they fit into the flow of your application. This is followed 
by detailed descriptions of all text editing procedures and functions - " 
their parameters, calling protocol, effects, side effects, and so on. 

Following these descriptions is a section containing notes for 
programmers who will use TextEdit from assembly language. 

Finally, there's a summary of the TextEdit data structures and routine 
calls, for quick reference, and a glossary of terms used in this 
manual . 
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ABOUT TEXTEDIT . 

TextEdit is a group of compact and efficient routines that provide the 
basic text editing and formatting capabilities needed in an 
application. These routines perform operations such as: 

- Inserting new text 

- Deleting characters that are backspaced over 

- Translating mouse activity into text selection 

- Moving text within a window 

- Deleting selected text and possibly inserting it elsewhere, or 
copying text without deleting it 

Because these routines follow the Macintosh User Interface Guidelines, 
using them ensures that your application presents a consistent, 
easy-to-learn interface for end users. In particular, TextEdit 
supports these standard features: 

- Selecting text by clicking and dragging with the mouse, 
double-clicking to select words instead of characters. 

- Inverse highlighting of the current text selection, or display of 
a blinking vertical bar at the insertion point. 

- Word wrap , which prevents words from being split between lines 
when text is drawn. To TextEdit, a word is any series of printing 
characters, excluding spaces (ASCII code $20) but including 
nonbreaking spaces (ASCII code $CA). 

- Cutting (or copying) and pasting within an application via the 
Clipboard *** not currently described, as "Clipboard" in the User 
Interface Guidelines, but will be ***. TextEdit puts text you cut 
or copy into a string of characters called the scrap . 

(hand) 

Cutting and pasting between applications, or between 
applications and desk accessories, is done with the aid 
of the Scrap Manager (see the Scrap Manager manual for 
details). 


THE EDITING ENVIRONMENT: EDIT RECORD 

To edit text on the screen, the text editing routines need to know 
where and how to display the text, where to store the' text, and other 
information related to editing. This display, storage, and editing 
information is contained in an edit record that defines the complete 
editing environment. The data type of an edit record is called TERec. 
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You prepare Co edit text by passing, to a procedure, a destination 
rectangle in which to draw the text and a view rectangle in which the 
text will be visible* The procedure incorporates the rectangles and 
the drawing environment of the current grafPort into an edit record, 
and returns a handle to the record: 

TYPE TEPtr - “TERec ; 

TEHandle - “TEPtr; 

Most of the text editing routines require you to pass this handle as a 
parameter. 

In addition to the two rectangles and a description of the drawing 
environment, the edit record also contains: 

- A handle to the text to be edited 

- A pointer to the grafPort 

“ The current selection range , which determines exactly which 
characters will be affected by the next editing operation 

~ The justification of the text, as left, right, or center 

The special terms introduced here are described in detail below. 

Most programmers won't access any of the fields of an edit record 
directly, and so don't have to know its exact structure; the necessary 
access is done with TextEdit routines. Advanced programmers, however, 
may need to know some of the field names. The structure of an edit 
record is given below. 


The Destination and View Rectangles 

The destination rectangle is the rectangle in which the text is drawn. 
The view rectangle is the rectangle within which the text is actually 
visible. In other words, the view of the text drawn in the destination 
rectangle is clipped to the view rectangle (see Figure 1). 
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Figure 1. Destination and View Rectangles 

You specify both rectangles in the coordinate system of the grafPort. 

In a document window, the destination rectangle should be inset about 
four pixels from the left and right edges of the graf Port's portRect 
(20 pixels from the right edge if there's a scroll bar or sise box) to 
ensure that the first and last character in each line is legible* 

Edit operations may of course lengthen or shorten the text* If the 
text becomes too long to be enclosed by the destination rectangle, it's 
simply drawn beyond the bottom* In other words, you can think of the 
destination rectangle as bottomless — its sides determine the beginning 
and end of each line of text, and its top determines the position of 
the first line* 

Normally, at the right edge of the destination rectangle, the text 
automatically wraps around to the left edge to begin a new line* A new 
line also begins where explicitly specified by a Return character in 
the text* Word wrap ensures that words are never split between lines 
unless they're too long to fit entirely on one line. 


The Selection Range 

In the text editing environment, a character position is an index into 
the text, with position 0 corresponding to the first character. The 
edit record includes fields for character positions that specify the 
beginning and end of the current selection range, which is the series 
of characters at which the next editing operation will occur. For 
example, the procedures that cut or copy from the text of an edit 
record do so to the current selection range. 

The selection range, which is always inversely highlighted, extends 
from the beginning character position up to but NOT including the end 
position. Figure 2 shows a selection range defined by the beginning 
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position 2 and the end position 7; it consists of five characters, 
those at positions 2 through 6. The end position may be 1 greater than 
the position of the last character of the text, so that the selection 
range can include the last character* 


Th|Hection range is inversely 
highlighted 


Selection range 
beginning at position 2 
and ending at position 7 


The| insertion point is marked with a 
blinking carat 

Insertion point 
at position 3 


Figure 2. Selection Range and Insertion Point. 

If the beginning and end of the selection range are the same, that 
character position Is the text's insertion point , the position where 
characters will be inserted. By convention, it's usually marked with a 
caret that blinks (is repeatedly inverted)* If, for example, the 
Insertion point is as illustrated in Figure 2 and the inserted 
characters are " edit", the text will read "The edit insertion 
point • • • " * 

(hand) 

We use the word caret here generlcally, to mean a symbol 
indicating where something is to be inserted; the 
specific symbol is a vertical bar. TextEdit does not 
automatically change the caret to a vertical bar for you. 

(You must use the QuickDraw procedure SetCursor.) 

If you call a procedure to insert characters when there's no insertion 
point (that is, when there's a selection range of one or more 
characters), the editing procedure automatically deletes the selection 
range and replaces it with an insertion point, before inserting the 
characters. 
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Justification 

TextEdit allows you to specify the justification of the lines of text, 
that is, their horizontal placement with respect to the left and right 
edges of the destination rectangle* The different types of 
justification are illustrated in Figure 3* 

- Left justification aligns the text with the left edge of the 
destination rectangle* This is the default type of justification. 

- Center justification centers the text between the left and right 
edges of the destination rectangle* 

- Right justification aligns the text with the right edge of the 
destination rectangle. 


This is an example 


This is an example 

of left 


of right 

justification See 


justification. See 

how the text is 


how the text is 

aligned with the 


aligned with the 

left edge of the 


right edge of the 

rectangle. 


rectangle. 


Thb is an example 
of center 

justification. See 
how the text is 
centered between 
the edges of the 
rectangle. 


Figure 3. Justification 


(hand) 

Trailing and leading spaces on a line are Ignored for 
justification. For example, "Fred" and " Fred " will be 
aligned identically. 

TextEdit has three predefined constants for setting the 
justification: 

CONST teJustLeft - 0; 
teJust Center - 1 ; 
teJustRight * -l ; 
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The TERac Data 


For Chose vho wane Co know more about tlte structure of an edit record, 
some (but not all) of "the structure Is given here. You can skip thi»- 
section if you vant and still use TextEdit as described above, but 's. -.as 
TextEdit features are available only if you change fields in the edit 
record directly. 


(eye) 


The fields that are not described e?eist solely for 
Internal use among the text editing routines; their 
contents cannot be predicted and must not be changed. 


TYPE TERec 


RECORD 

destRect: Rect; {destination rectangle} 

vievRect: Rect; {view rectangle} 

llneHelght: INTEGER; {line height} 

firstBL: INTEGER; {location of firtt base line} 

selStart: INTEGER; {start of selection range! 

selEnd: INTEGER; {end of selection range} 

just: INTEGER; {justification} 

length: INTEGER; {length of text} 

hText: Handle; {text to be edited} 

txFont: INTEGER; {text font} 

txFace: INTEGER; {character style} 

txMode: INTEGER; {pen mode} 

txSize: INTEGER; {type size} 

inPort: GrafPtr; {grafPort} 

crOnly: INTEGER; {new line at Return only, if <0} 

nLines: INTEGER; {number of lines} 

lineStarts: ARRAY {0.. 32000] OF INTEGER 

{positions of line starts} 

{some fields within the record are for internal use 
only, and aren't shown here; see the Pascal Interface 
to TextEdit} 

END; 

Any of the fields in the edit record can be changed, at your 
discretion* Clearly, some fields (such as length, hText, 
inPort, and crOnly) might be changed frequently. The lineStarts 
array should be left unchanged* 

The lineHelght field, specifies the line height of the text , the number 
of pixels from the base line of one line to the base line of the next 
line, as shown in Figure 4. For single-spaced lines, line height is 
the same as the type size, for double-spaced lines, line height is 
twice the type size, and so on. 
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singia-spacati 


HirctSL 



■ line height 
• type size 

double-spaced 



Figure 4. Line Height and FirstBL 


The firstBL field specifies the number of pixels from the top of the 
destination rectangle to the base line of the first line of text. 
Initially the firstBL field is set for single-spaced lines, but you can 
change it for any other spacing you want. For example, to change from 
single to double spacing, use 

firstBL :■ firstBL + typeSize 
line Height 2 * typeSize 

where typeSize is the type size of the text. 

The hText field is a handle to the text to be edited, and the length 
field contains the number of characters in the text. You can directly 
change the text of an edit record by changing these two fields. 

The crOnly field specifies whether or not text wraps around at the 
right edge of the destination rectangle, as shown in Figure 5. If 
crOnly is zero or positive, text does wrap around. If crOnly is 
negative, text does not wrap around at the edge of the destination 
rectangle, and new lines are specified explicitly by Return characters 
only. This is somewhat faster than wrap around, ‘and is useful in 
applications such as a programming-language editor, where you don't 
want a single line of code to be split onto two or more lines. 
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There's a Return 
ch ar ac ter at the end 
of this line. 

But not at the end of 
this line. Or this line. 


New line at Return 
cha r a cter s and edge of 
destination rectangle. 


There's a Return chared 
But not at the end of tn 


New line at Return 
ch ar ac ter s only. 


Figure 5. New Lines 


The nLines field contains the nuaber of lines in the text. The 
lineStarts array contains the character position of the first character, 
in each line. It’s declared to have 32001 elements to comply with 
Pascal range checking; it’s actually a dynamic data structure having 
only as many elements as needed. 

(hand) 

The values of the lineStarts array, selEnd, and selStart 
are stored internally as unsigned integers. Be aware 
that negative values passed from Pascal will be 
Interpreted as greater than 32767. 


USING TEXTEDIT 

This section discusses how the text editing routines fit into the 
general flow of an application program and gives you an idea of what 
routines you'll need to use. The routines themselves are described in 
detail in the next section. 

Before using TextEdit, you should Initialize QuickDraw, the Font 
Manager, and the Window Manager, in that order. 

The first TextEdit routine to call is the initialization procedure 
TEInlt. Call TENew to allocate an edit record; it returns a handle to 
the record. Most of the text editing routines require you to pass this 
handle as a parameter. 

To make a blinking caret appear at the insertion point, call the TEIdle 
procedure as often as possible; if it's not called often enough, the 
caret will blink irregularly. 

Your application's "main loop" should call the Toolbox Event Manager 
function GetNextEvent to learn whether any events have occurred. 

Events that pertain to TextEdit need to be handled by TextEdit 
routines. Whenever a mouse down event occurs within the view 
rectangle, call the TEClick procedure. TEClick automatically controls 
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the placement of the selection range and insertion point (including 
supporting use of the Shift key to make extended selections). 

There are several procedures available for editing text. Usually they 
are called in response to mouse down events and menu selections. The 
editing procedures are: 

- TEKey inserts characters at the insertion point, and deletes 
characters backspaced over. 

- TECut transfers the selection range to the scrap, removing it from 
the text, and TEPaste inserts the scrap at the insertion point. 

By calling TECut, changing the insertion point, and then calling 
TEPaste, you can perform a "cut and paste" operation, moving text 
from one place to another. 

- TECopy copies the selection range to the scrap. By calling 
TECopy, changing the insertion point, and then calling TEPaste, 
you can make multiple copies of text. 

- TE Delete removes the selection range (without transferring it to 
the scrap). 

- TEInsert inserts text at the insertion point. You can use this to 
combine two or more documents. TEDelete and TEInsert do not 
modify the scrap, and consequently are useful for implementing the 
Undo command (as described in the Macintosh User Interface 
Guidelines). 

After each editing procedure, the text is redrawn from the insertion 
point to the end of the destination rectangle. You never have to pass 
the selection range or insertion point to the editing procedures; the 
procedures simply access that information from the edit record. The 
editing procedures and TEClick leave the selection range or insertion 
point where it should be, according to the Macintosh User Interface 
Guidelines, so you don't have to set it yourself. But, in case you 
want to, you can modify the selection range directly by using the 
TESetSelect procedure. 

Every time Get Next Event reports an update event for the text editing 
window, call TEUpdate (along with the Window Manager procedures 
BeginUpdate and EndUpdate), to redraw the text. 

(hand) 

Advanced programmers: you must call TEUpdate after you 
change any fields of the edit record if the fields affect 
the appearance of the text. This ensures that the screen 
accurately reflects the changed editing environment. 

The procedures TEActivate and TEDeactivate must be called each time the 
Event Manager reports an activate event for the text editing window. 
TEActivate simply highlights the selection range or displays a caret at 
the insertion point, and TEDeactivate unhighlights the selection range 
or removes the caret. 
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To specify the justification of the text, you can use TESetJust (which 
requires calling TEUpdate). 

If at any tlae you want to change the text being edited, you can do so 
by calling TESetText. A common technique (used in dialog boxes, for 
instance) is to allocate a single edit record for several separate 
pieces of text where only one may be edited at a time; this saves 
having to allocate an edit record for each of them. 

When you've finished working with the text of an edit record, you can 
get a handle to the text by calling TEGetText. When you're completely 
done with an edit record and want to dispose of it, call TEDispose, 
which removes the text and edit record from the heap. 

If you ever want to draw text in any given rectangle (without being 
able to edit it), use the TextBox procedure. 

Advanced programmers may wish to use the TEScroll procedure, to move 
text within the view rectangle, or TECalText, to recalculate the 
beginning of each line after changing the text or the destination 
rectangle. 


TEXTEDIT ROUTINES 


This section describes all the procedures and functions in TextEdit. 
They are presented in their Pascal form; for information on using them 
from assembly language, see "Using the Toolbox from Assembly Language" 
*** doesn't exist, but see the QuickDraw manual *** and also "Notes 
for Assembly-Language Programmers" in this manual. 


Ini tialization 


PROCEDURE TEInit; 

TEInit initializes TextEdit by allocating a handle for the scrap. The 
scrap is Initially empty. Call this procedure once and only once at 
the beginning of your program. 


FUNCTION TENew (destRect ,viewRect : Rect) : TEHandle; 

TENew allocates a handle for the text, builds and initializes an edit 
record, and returns a handle to the new edit record. DestRect and 
viewRect are the destination and view rectangles, respectively. Both 
rectangles are specified in the current grafPort's coordinates. Call 
this procedure once for every edit record you want allocated. The edit 
record incorporates the drawing environment of the grafPort, and is 
initialized for left-justified, single-spaced text with an insertion 
point at character position 0. 
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Manipulating Edit Records 


PROCEDURE TESetText (text: Ptr; length: Longlnt; hTE: TEHandle); 

TE Set Text takes the specified text and incorporates it into the edit 
record specified by hTE. The text parameter points to the text, and 
the length parameter indicates the number of characters in the text. 
The selection range is set to an insertion point at the end of the 
text. TESetText does not affect the text drawn in the destination 
rectangle, so call TEUpdate (described below) afterwards. 


FUNCTION TEGetText (hTE: TEHandle) : CharsHandle; 

TEGetText returns a handle to the text of the edit record specified by 
hTE. The CharsHandle data type is defined as: 

CharsHandle « “CharaPtr; 

CharsPtr - “Chars; 

Chars - PACKED ARRAY [0.. 32000 ] OF CHAR; 


Vo '5 

- PROCEDURE TEDiapose (hTE: TEHandle); 

TEDispose deallocates the space allocated for the edit record and text 
specified by hTE, and returns the memory to the free memory pool. Call 
this procedure when you're completely through with an edit record. 





Editing 




PROCEDURE TEKey (key: CHAR; hTE: TEHandle); 

TEKey replaces the selection range in the text specified by hTE with 
the character given by the key parameter, and leaves an insertion point 
just past the inserted character. If the selection range is an 
insertion point, TEKey just inserts the character there. If the key 
parameter contains a Backspace character, the character immediately to 
the left of the insertion point is deleted. Call TEKey every time the 
Toolbox Event Manager function GetNextEvent reports a keyboard event 
that your application decides should be handled by TextEdit. 

(eye) 

TEKey blindly inserts every character passed in the key 
parameter, so it's up to your application to filter out 
all characters that aren't actual text (such as keys 
typed in conjunction with modifier or special keys). 
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PROCEDURE TECut (hTE: TEHandle); 

TECut resow* tht aclecCion range froa the text specified by hTE and 
places it- In the scrap* Anything previously in the scrap is deleted. 
(See Figure 6.) If the selection range is an Insertion point, the 
scrap is eaptled. 


This i 



a good illustration 


Text 



Before TECut 


This is a good illustration 
Taxi 


probably 

Scrap 


After TECut 


Figure 6. Cutting 


PROCEDURE TECopy (hTE: TEHandle); 

TECopy copies the selection range froa the text specified by hTE into 
the scrap* Anything previously in the scrap is deleted* The selection 
range is not deleted* If the selection range is an insertion point, 
the scrap is emptied* 


PROCEDURE TEPaste (hTE: TEHandle); 

TEPaste replaces the selection range in the text specified by hTE with 
the scrap, and leaves an insertion point just past the Inserted text* 
(See Figure 7.) If the scrap is empty, the selection range is deleted* 
If the selection range is an insertion point, TEPaste just inserts the 
scrap there* 
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store you leap 


Text 



Before TECut 


jbefore you leap 


look, 

Text 

After TECut 

Scrap 

J before you ^eap 


Jloofc, 

Text 


Scrap 


Before TEPaste 


before you look, leap 
Text 


look; 

Scrap 


After TEPaste 


Figure 7 . Cutting and Pasting 


PROCEDURE TE Delete (hTE : TEHandle) ; 

TEDelete removes the selection range from the text specified by hTE. 
It's the same as TECut (above) except that it doesn't transfer the 
selection range to the scrap. If the selection range is an insertion 
point, nothing happens. 


PROCEDURE TE Insert (text: Ptr; length: Longlnt; hTE: TEHandle); 

TE Insert takes the specified text and inserts it, just before the 
selection range, into the text indicated by hTE. The text parameter 
points to the Inserted text, and the length parameter indicates the 
number of characters to be inserted. 

(eye) 

Any current selection range is not deleted. This is 
different from TEKey and TEPaste, and allows your 
application to support the Undo command (described in the 
Macintosh User Interface Guidelines) if you want. 
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Selection Range and Justification 


PROCEDURE TESetSelect (selStart .selEnd : Longlnt; hTE: TEHandle); 

TESetSelect unhlghllghts the current selection range, and changes It to 
selStart and selEnd In the text specified by hTE. The new selection 
range Is highlighted. If selStart and selEnd are equal, the selection 
range is an insertion point, and a caret is displayed. 

SelEnd and selStart can range from 0 to 65535. If selEnd is anywhere 
beyond the last character of the text, the position just past the last 

character is used. _ . r. , -r- 

(?> - <sfi — ius 

! 

PROCEDURE TESetJust (j: INTEGER, hTE: TEHandle); 

TESetJust changes the justification of the text specified by hTE to j. 

(See "Justification" under "The Editing Environment: Edit Record".) 

Call TEUpdate (described below under "Text Display") after TESetJust to' 
cause the text to be redrawn with the new justification. 


Mice and Carets 


PROCEDURE TEClick (pt: Point; extend: BOOLEAN; hTE: TEHandle); 

TEClick controls the placement and highlighting of the selection range 
as determined by mouse down events* Call TEClick whenever a mouse down 
event occurs in the view rectangle of the edit record specified by hTE. 
Pt is the mouse location (in local coordinates) at the time the button 
waa pressed, obtainable from the event record. Pass TRUE for the 
extend parameter if the Event Manager indicates that the Shift key was 
held down at the time of the click* (for an extended selection range). 

(eye) 

Use the QuickDraw procedure GlobalToLocal to convert the 
global coordinates of the mouse location given in the 
event record to the local coordinate system for pt. 

If the mouse moves, meaning that a drag is occurring, the selection 
range expands or shrinks accordingly. The current selection range is 
unhighllghted. In the case of a double click, meaning that word 
selection has been chosen, the word under the cursor becomes the 
selection range. 
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PROCEDURE TEIdle (hTE: TEHandle); 

Call TEIdle repeatedly to make a blinking caret appear at the insertion 
point, if 'any, in the text . specified by hTE. TextEdit observes a 
minimum blink interval: no matter how often you call TEIdle, the time 
between blinks will never be less than the minimum interval. You 
should call this procedure as often as possible to provide a constant 
frequency of blinking. 

(hand) 

, The initial minimum blink interval setting is 4 ticks 
(sixtieths of a second). The user can adjust this 
setting to individual preference with the control panel 
desk accessory. 


PROCEDURE TEActivate (hTE: TEHandle); 

TEActivate highlights the selection range in the view rectangle of the 
edit record specified by hTE. If the selection range is an insertion 
point, it displays a caret there. This procedure should be called 
every time the Toolbox Event Manager function GetNextEvent reports that 
the text editing window has become active. 


PROCEDURE TEDeactivate (hTE: TEHandle); 

TEDeactivate unhighlights the selection range in the view rectangle of 
the edit record specified by hTE. If the selection range is an 
insertion point, it removes the caret. This procedure should be called 
every time the Toolbox Event Manager function GetNextEvent reports that 
the text editing window has become inactive. 


Text Display 


PROCEDURE TEUpdate (rUpdate: Rect; hTE: TEHandle); 

TEUpdate drawa the text specified by hTE within the rectangle specified 
by rUpdate. The location of the rUpdate rectangle must be given in the 
coordinates of the grafPort. Call TEUpdate every time the Toolbox 
Event Manager function GetNextEvent reports' an update event after you 
call the Window Manager procedure BeginUpdate, and before you call 
End Update. 

Normally you’ll use the following when an update event occurs: 
BeginUpdate(myWindow) ; 

TEUpdate ( my Wi ndow'* .vis Rgn~ ~ . r gnBBox » hTE) ; 

EndUpdate(myWindow) ; 
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Instead of passing rUpdate as shown, you can pass the vlewRect, but 
doing so nay result in unnecessary drawing. 


PROCEDURE TextBox (text: Ptr; length: Longlnt; box: Rect; j: INTEGER); 

TextBox draws the specified text in the rectangle indicated by the box 
parameter, with justification j. (See "Justification" under "The 
Editing Environment: Edit Record".) The text parameter points to the 
t#xt , and the length parameter indicates the number of characters to 
draw. TextBox does not create an edit record, nor can the text that it 
draws be edited immediately; it's used solely for drawing text. For 
example: 

str :■ 'Planning Procedures'; 

SetRect(r, 104, 100, 200, 200); 

TextBox(@str[ 1 ] , LENGTH(str) , r, teFillCenter) ; 

FrameRect(r); 


Advanced Routines 


These routines are useful only if you're directly accessing the fields 
of an edit record. 


PROCEDURE TEScroll (dh,dv: INTEGER; hTE: TEHandle); 

TE Scroll moves ("scrolls") the text within the view rectangle of the 
specified edit record by the number of pixels specified in the dh and 
dv parameters. The edit record is specified by the hTE parameter. 
Positive dh and dv values move the text right and down, respectively, 
and negative values move the text left and up* For example,. 

TEScroll(0 , -InHeight , hTE) 

scrolls the text up one line (where InHeight is the value of the 
lineHeight field in the edit record). 


PROCEDURE TECalText (hTE: TEHandle); 

TECalText recalculates the beginnings of all lines of text in the edit 
record specified by hTE, updating elements of the lineStarts array. 

Call TECalText if you've changed the destination rectangle, the hText 
field, or anything else that effects the number of characters per line. 

(hand) 

There really are two ways to specify text to be edited. 

The easiest, direct method is to use TESetText, which 
takes an existing edit record, creates a second copy of 
its text, and makes the edit record point to the copy. 

An advanced, indirect method is to change the hText field 
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of the edit record directly, and then call TECalText to 
recalculate the lineStarts array to match the new text* 

If you have a lengthy text to edit, use the latter method 
to save space because it doesn’t create a copy* 


NOTES FOR ASSEMBLY-LANGUAGE PROGRAMMERS 


Information about how to use the User Interface Toolbox from assembly 
language is given elsewhere *** (currently, in the QuickDraw manual) 
***. This section contains special notes of interest to programmers 
who will be using TextEdit from assembly language* 

If you use .INCLUDE to include a file named ToolEqu.Text when you 
assemble your program, the TextEdit constants and offsets into the 
fields of structured types in TextEdit will be available in symbolic 
form. 

There are hooks within TextEdit that allow you insert additional 
procedures for more sophisticated editing. They require some care 
because they pass arguments in registers and it's the application's 
responsibility to save and restore the registers* 

Two of the hooks are TEHiHook and TECarHook. If you install a nonzero 
address in either of these hooks, that address (instead of _InverRect) 
will be jumped to when a selection range is to be highlighted* The 
routine called can destroy the contents of the registers A 0, A1 , D0 , 

D1 , and D2. A3 will be pointing to a locked edit record, and 
teSelRect( A3) contains the rectangle enclosing the text being 
highlighted. For example, the following assembly-language fragment 
draws underlined selection ranges: 

UnderHigh 


MOVE.L 

(SP)+,A0 

; point to rectangle to be 
; highlighted 

MOVE 

top(A0),-(SP) 

;save existing top coordinate 

MOVE 

bottom(A0) ,top(A0) 

;make the top coordinate equal 

SUBQ 

#1 , top(SP) 

; the bottom coordinate - 1 

MOVE.L 

A0,-(SP) 

;invert the resulting 


__InverR*ct ; rectangle 

MOVE (SP)+,teSelRecc+top(A3) .restore original top coordinate 
RTS 

Note that the rectangle must be preserved* 

TECarHook acts analogously upon insertion points instead of selection 
ranges* It must be called with teSelRect containing the insertion 
point rectangle* 

*** The explanation of the other hooks is forthcoming. *** 
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SUMMARY OP TEXTEDIT 


CONST teJuatLef t - 0; 

teJustCenter “ 1 ; 
teJust Right - -1 ; 


be Fid. - - 


TYPE CharsHandle 
Chars Ptr 
Chars 


'CharsPtr; 

'Chars; 

PACKED ARRAY [0.. 320001 OP CHAR; 


TEPtr 

TEHandle 

TERec 


'TERec; 

'TEPtr; 

RECORD 


destRect: 

Rect; 

{destination rectangle} 

vlewRect: 

Rect; 

{view rectangle} 

line Height: 

INTEGER; 

{line height} 

flrstBL: 

INTEGER; 

{position of first base line} 

selStart: 

INTEGER; 

{start of selection range} 

selEnd: 

INTEGER; 

{end of selection range} 

just: 

INTEGER; 

{justification} 

length: 

INTEGER; 

{length of text} 

hText : 

Handle ; 

{text to be >edited} 

txFont: 

INTEGER; 

{text font} 

txFace : 

INTEGER; 

{character style} 

txMode : 

INTEGER; 

{pen mode} 

txSize : 

INTEGER; 

{type size} 

inPort : 

Graf Ptr; 

{grafPort} 

crOnly : 

INTEGER 

{new line at Return only, if 

nLines : 

INTEGER; 

{number of lines} 

lineStarts : 

ARRAY (0. 

.32000] OP INTEGER; 


{more fields 
END; 


{positions of lines starts} 
for internal use only} 


Initialization 


PROCEDURE TEInit; 

FUNCTION TENew (destRect „viewRect : Rect) : TEHandle; 


Manipulating Edit Records 

PROCEDURE TESetText (text: Ptr; length: Longlnt; hTE: TEHandle); 
FUNCTION TEGetText (hTE: TEHandle) : CharsHandle; 

PROCEDURE TEDispose (hTE: TEHandle); 
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Editing 

PROCEDURE TEKey ( key : CHAR ; hTE : TEHand le ) ; 

PROCEDURE TECut (hTE: TEHand le); 

PROCEDURE TECopy (hTE: TEHandle); 

PROCEDURE TE Paste (hTE: TEHandle); 

PROCEDURE TEDelete (hTE: TEHandle); 

PROCEDURE TE Insert (text: Ptr; length: Longlnt; hTE: TEHandle); 


Selection Range and Justification - 

PROCEDURE TESetSelect (selStart .aelEnd : Longlnt; hTE: TEHandle); 
PROCEDURE TE Set Just ( j : INTEGER; hTE: TEHandle); 


Mice and Carets 


PROCEDURE TEC lick 
PROCEDURE TEIdle 
PROCEDURE TEActivate 
PROCEDURE TE Deactivate 


(pt: Point; extend: 
(hTE: TEHandle); 
(hTE: TEHandle); 
(hTE: TEHandle); 


BOOLEAN; hTE: TEHandle); 


Text Display 

PROCEDURE TEUpdate (rUpdate: Rect; hTE: TEHandle); 

PROCEDURE TextBox (text: Ptr; length: Longlnt; box: Rect; j: INTEGER); 


Advanced Routines 


PROCEDURE TE Scroll (dh.dv: INTEGER; hTE: TEHandle); 
PROCEDURE TECalText (hTE: TEHandle); 
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GLOSSARY 


caret: A generic tern meaning a symbol that indicates where something 
should be Inserted in text. The specific symbol used is a vertical 
bar. 

character position: An index into an array containing text, starting 
at 0 for the first character. 

destination rectangle: In TextEdit, the rectangle in which the text is 
drawn. 

edit record: A complete editing environment, including the text to be 
edited, the grafPort and rectangle in which to display the text, the 
arrangement of the text within the rectangle, and other editing and 
display information. 

insertion point: An empty selection range; the character position 
where text will be inserted (marked with a blinking caret by 
convention). 

justification: The horizontal placement of lines of text relative to 
the edges of the rectangle in which the text is drawn. 

line height: The number of pixels from the base line of one line of 
text to the base line of the next line of text. 

nonbreaking space: The character with ASCII code $CA; drawn as a 
blank, but interpreted as a nonblank character for the purposes of word 
wrap . 

scrap: A string consisting of the characters most recently cut or 
copied from text by certain TextEdit routines. 

selection range: The series of characters (inversely highlighted), or 
the character position (marked with a blinking caret), at which the 
next editing operation will occur. 

view rectangle: In TextEdit, the rectangle within which the text is 
visible. 

word: In TextEdit, any series of printing characters, excluding spaces 
(ASCII code $20) but including nonbreaking spaces (ASCII code $CA). 

word wrap: Keeping any series of printing characters intact between 
lines when text is drawn. 
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The Macintosh Finder — Specification and Implementation Notes 


Bruce Horn 29 May 1983 


This document describes the Macintosh Finder as it is being implemented# 
This is a WORKING document. Any improvements, changes, etc. will be considered 
for the final version of the Finder. 

{ My comments and questions are marked with brackets like this. } 

Please note anything that you think I should be aware of, or should change, 
and let me know. 


r 
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Finder Description and Goals 


The Finder is the first application encountered by Macintosh users. 

Because of this, it must work simply and intuitively, and it must conform 
to the Macintosh User Interface Standard so that the procedures learned by 
using the Finder may be used in the other Macintosh applications. 

The goals of the Finder are very simple: 

1) It must make the common tasks of deleting, copying, transferring, 
organizing and renaming files intuitive and fast. 

2) Initializing and renaming diskettes must also be easy. . Copying entire 
diskettes must be quick and as painless as possible, given the large 
probability of a single-drive system. Damaged diskettes must be able 
to be recovered, whenever possible. 

3) It should allow the user to start an application with a given document 
quickly, with a minimum of typing. 

4) It must allow access to any devices connected to the Macintosh, 
including devices connected on the AppleBus. 

5) System configuration should be simple and straightforward. Adding 
new fonts, icons, and other system resources should be as easy as 
dragging a file on the desktop. Adding drivers for new devices on 
the AppleBus should be very simple. 

These features, and others, will be implemented in the Finder using the 
Desktop Model. 


The Finder Objects (well, not really) 


All objects which are manipulated by the Finder are represented as icons 
with names below. These icons, as well as windows, are displayed on the gray 
Desktop. The icons and windows may be dragged around, selected and deselected, 
and otherwise organized by the user. Given certain restrictions, objects may be 
dragged into windows or dropped into other objects, called "receptacles , " which 
perform different actions depending on what the object and receptacle are. The 
Finder objects may also be opened, to inspect the "contents," which of course 
differs depending on what kind of object was opened. 

When the sentence "on the desktop" is used, it may be read to mean "either 
on the desktop or in a window." 
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Types of Objects 


There are several kinds of objects which can live- on the Finder desktop: 


1 ) 



Files, which represent diskette applications and documents. When 
an application is opened, the Finder launches that application which 
starts up with a null document. If a document is opened, that 
document’s primary application is started, which loads in the document 
initially. The primary application is usually the application which 
created that document, though that is not necessarily the case. 

Folders, objects which allow grouping of other objects of any kind 
except diskettes. When opened, folders show the objects grouped 
together in a spatial format, with icons, or in either an alphabetical 
or chronological format, with lines of text that can be scrolled. 

Diskettes, which represent diskettes either on or off-line, and when 
opened, show files and folders. Like folders, the contents of the 
diskette may be displayed spatially, alphabetically, or chronologically. 

Desk accessories, which are implemented as drivers with windows. For 
example, the calculator and the puzzle are desk accessories. When opened, 
the desk accessory opens up into the accessory window. 

Finder-specific desk accessories. These are desk accessories which 
respond to special control calls which the Finder makes use of. 

Examples of finder-specific desk accessories are the "Resource 
Representatives," desk accessories which allow manipulation of the 
system resources including fonts, other drivers, icons, pictures, 
and so on, and a "picture printer," which prints QuickDraw picture 
files from the Finder. 

A waste basket, which is used only for deleting objects. Files, 
resources, folders, and other objects may be deleted by dragging them 
to the waste basket. Some objects, such as diskettes, may not be 
deleted in this way. When opened, the waste basket shows the last 
few files deleted, and allows undeleting of those files by dragging 
them out of the waste basket and back onto the desktop. { I like 
a waste basket a lot better than a garbage can ... but isn’t there 
anytning better? } 



A clipboard, which shows the contents of the scrap as it was when the 
last application terminated. The scrap is not changed when the editing 
ommands in the Finder are used; there is another hidden scrap for this 
purpose. { I definitely don’t like the clipboard for the scrap... } 
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Selecting and Views 


An object may be selected in two ways: by clicking once on the icon 
or the name, or by including it in a group selection. A group selection is 
done by clicking in the gray area outside of any object, dragging out a rectangle 
which includes the objects that are to be in the group selection, and releasing 
the mouse button. All the objects which have the middle point of the icon 
in the rectangle are selected, if they can be. (They may already be open, in which 
case they cannot be selected.) Another way to make a group selection is to 
select icons one by one, holding down the shift key. If the shift key is not 
held down, previously-selected objects are deselected when a new selection 
occurs, but if the shift key is down, the previous selections remain. 

The entire group selection must be contained entirely on the desktop or in 
a window. The selection may not include objects in more than one window, or 
objects in a window and objects on the desktop. 


Objects on the desktop are shown in several' states. Normally the object 
will be displayed as the icon itself, with the name below. When the object is^J^ 
selected, both the name and the icon will be inverted* { This may change 
When the object is opened, zooming rectangles indicate the source rectangle of 
the icon and the destination rectangle of the window. When the window is 
displayed, a "ghost" of the icon remains on the desktop, which is just a white 
shadow of the icon shape. Objects which are not immediately accessabl^, . such 
as off-line diskettes, are showed "dimmed," grayed out slightly. These objects 
may be selected and dragged just like other objects, but when they are opened or 
otherwise included in an operation, the Finder may request a diskette to be 
inserted for the object to be found. 


All objects are named. They may be renamed by the user simply by selecting 
the object to be renamed and typing; this results in the previous name being 
replaced by the new name. The Finder also supports mouse editing of the name: 
once the object is selected, the pointer appears as an I-beam over the text, and 
the Cut/Paste/Copy/Undo editing commands may be used from the edit menu. 


Dragging 


Objects are dragged exactly as windows are dragged. Clicking on the object 
selects it, and holding the mouse button and moving the mouse drags a flickering 
outline of the icon and the name, and when the button is released, the object 
snaps to the new location. { This may change to drag the entire icon, saving the 
bits under. That is kind of expensive for formation dragging, which is explained 
below. } If several objects are selected at once, dragging one of the objects 
will drag the others in formation. When a formation is being dragged, only the 
icon which is the "handle" is looked at when an operation is being attempted, 
such as dropping the group into the picture printer, or dragging the group to a 
diskette to be copied. 
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When an object is being dragged over another object which is a receptacle, 
the receptacle object will invert to show that it can. accept the object being 
dragged. If it cannot accept it, the receptacle will not invert. If the object 
being dragged is dropped on the receptacle, either the receptacle will take 
the object and perform an action, or the object will animate back to its original 
position. 

There is a small hysteresis implemented in the dragging routine, which 
requires the user to move at least 3 pixels in any direction before the dragging 
begins. This prevents the user from accidentally moving the object when just 
trying to click on it. 

Dragging objects may cause various actions to occur, which are described 
later in the section titled "Operations by Dragging." 


Opening 


An object may be opened two ways: by selecting it and choosing the Open 
command in the File menu, or by double-clicking on the icon. The icon will then 
turn to the "ghost" icon, zooming rectangles will indicate the destination of the 
window, and the window will appear with the object contents displayed inside. 


Closing 


An opened object may be closed by clicking on the close box of the window, 
by selecting the window and choosing Close in the File menu, or by choosing 
Close All in the File Menu, which will close all open windows back to their 
original icon objects. 


Windows in the Finder 


Windows in the Finder serve several purposes: to show the contents of 
Finder objects, for example diskettes and folders; to show object information, 
such as file size, object type, and file comment; or to show diagnostic or 
dialog information, including error messages or prompts to the user to swap 
diskettes. 
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Selecting and Dragging 


Windows are selected by clicking in their content or on the title bar. 

They may be dragged by the title bar to anywhere on the desktop. Dragging a 
window has no effect other than to change its position, i.e. no actions will occur 
with windows as they do with objects represented as icons. 


Sizing 


An opened diskette, folder, or waste basket may be sized using the grow 
box, as usual. Each object remembers the position and size of its window, so 
the window arrangement of your desk may be preserved. This is useful, for 
example, if the user would like to see both diskettes at once; each diskette 
window could take up 1/2 of the screen height, and the orientation would be 
kept for later use. 

Desk accessory windows, and Finder-rspecific desk accessories, may or may not 
allow growing, depending on what kind of accessory they are. Resource 
Representatives, which act like diskette windows to a certain extent, are likely 
to allow growing. 
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The Window Contents 


The only kind of window available for a File object is the Information 
window, since the result of opening a File object is to start its application. 
The Information window looks like the following: 


Syzygy Information 


Syzygy is a File object which lives on the 
diskette named AstroPhysics. 

Size: 14565 bytes 

Type: "MBit", a Mac Sketch document. 

Note 


This is the user comment. It currently exists only 
for files, though other objects could have them too, 
if that is desireable. The maximum length of this 
comment is 255 characters. This field is NOT a 
scrollable field in the window, but it is editable. 





The Information window may be brought up for any kind of object. For any 
kind of object other than File, the Size and Type fields are not shown, and 
there is no "Note" field* { This may change, if people think that it is useful* } 
This window does not "ghost" the icon; it may still be selected and opened, if 
desired* 


When a Folder is opened, it shows the objects which it contains in spatial 
format. The window is shaped like a folder, with a rounded tab on the upper 
left portion of the window, with the name of the folder inside. There are two 
special buttons in the lower right-hand corner of the window, on either side 
of the grow box, which contain the arrow and a hand. When the hand is selected, 
the cursor becomes a hand and two dimensional scrolling is accomplished by 
pressing the button down in the content and dragging. The object-plane moves 
accordingly, and is -updated when the mouse button is released. Selecting the 
arrow allows object selection and dragging within the window. { AIEE! MODES! 

( Shhh ! Modes aren’t allowed here! BUT I DON’T WANT SCROLLBARS, and I have to 
have some sort of mode to allow both selection and scrolling with the hand...} 
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/ Flight Designs 


Tripteron 


Mini Space Shuttle 


< — Arrow 
< — Grow box 

• Hand 


When a diskette is opened, its window shows the objects which live on the 
diskette. Any files or folders which are either on the desk or in another 
folder are not shown in the diskette window. The diskette may be scrolled in 
exactly the same way that the folder is scrolled. A pane at the top of the window 
shows how much room remains on the diskette and whether it is write-protected 
or not. 


Desk Accessories, either normal or Finder-specific, open up into custom 
windows designed for the accessory. For the different kinds of Resource 
Representatives, for example, there will be different ways to most effectively 
display what kind of resources are being inspected: for example, patterns, 
icons, and pictures can all be displayed as themselves, and fonts may be displayed 
by either name or example text in that font. 

The Waste Basket opens up into a window which is similar to a diskette 
window. The files which have been recently deleted are shown just as they 
were shown in the diskette window, but their position information is changed to 
strict rows and columns, since there is no reasonable way to record relative 
positions of each file. Folders are not shown in the waste basket, because they 
are deleted immediately and cannot be recovered, though the files which were 
in the folder are displayed, if possible. 

The Clipboard opens into a window which draws the picture of the latest 
non-Finder scrap. The picture is scaled to the window size, which can 
be grown or shrunk by dragging the grow box, as usual. { Should the picture be 
scaled? Is there any size information in the picture, which gives the "realRect" 
of the image? } 
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Menu Operations 


current Finder menu 

looks like the following: 


@ 

Edit 

File 

Arrangement 


Cut 

Open 

Pictorial 

Finder 1.0' 

Paste 

Get Info 

Alphabetical 


Copy 

Close 

Chronological 

May 29, 1983 

Undo 

Close All 




Put Back 

Clean Up 

Apple Computer 

Select All 

Duplicate 




Eject 



The Edit Menu 


The Edit menu provides the standard text editing commands which may be used 
to edit the object names below the icons, or the comment in the information 
window only. Text which is cut or copied goes to a special Finder scrap, which 
is invisible — the inter-application scrap is unaffected. 

Select All selects either the entire object name or information comment. 

It does not select objects. { Maybe it should be called Select All Text ? } 


The File Menu 


The File menu provides a range of operations on Finder objects. { Should 
the File menu be called something else? The Do It menu? The Icon menu? } 

Open opens a selected object, or objects, into their windows. If none of 
the objects is an application or a document, the objects are opened as expected. 
Their icons are ghosted, and the windows appear with the zooming rectangles. 

If no object is selected, or a window is selected, then a staged alert occurs, 
(it will only beep the first two times the error occurs, before an alert box 
is actually created). 

If an application is one of the selected objects, then: 

— If there are no other selections, the application will begin running 
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with no document loaded. 

— If there is one other selection and it is a non-application file, 
the application will start and attempt to load that file as its 
document. If it is not able, to edit that type of file, the 
application will bring up an alert box and then begin to edit 
an empty document. { Might want to have multiple files selected, for 
an assembler, for example... } 

— In any other case, no action will occur, and the Finder will 
bring up an alert box. 

Get Info brings up an information box. The object is not ghosted and may 
be selected, dragged and opened as usual. 

Close closes the topmost window. If the window is an information window, 
it just disappears. If the window is an object window of any kind, including 
a desk accessory window, zooming rectangles indicate the source window and the 
destination icon, and the icon is restored to its normal, selected view. 

Close All closes all open windows. Object windows zoom back to their icons, 
which all become selected. 

Put Back puts the selected object or objects back into their source folder 
or diskette. If a file is temporarily dragged from a folder to the desktop, 
selecting Put Back will cause that file to animate back to its original position 
in the folder. 

Duplicate creates a duplicate copy of the selected object. If the object 
is a file, a duplicate copy of that file is created on the same disk as the 
original, with the name initially set to M New OldName hh:mm:ss, ,, , where OldName 
is the name of the file which was copied ("Tripteron Top View") and hh:mm:ss 
is the time that the file was created. This is done so that there is no naming 
conflict due to duplicating old files. (Of course, malicious users may rename 
another file to one that already exists, or name a file to "New OldName... " and 
then choose Duplicate on the appropriate file. These cases are caught by the 
Finder and the user alerted.) The user may change the default name to one that 
is a little more descriptive, if desired. If the object is a disk, the user 
is lead through a swapping sequence to copy the disk (if the system is a single- 
drive system). If there are two drives, a dialog box will suggest that the 
disk to be copied to should be put in the external drive, and that a disk copy 
be done instead. 

Folders may also be duplicated. When this is done, all the files and 
sub-folders are duplicated as well. The naming coercion as described above 
occurs for each sub-object. 

If a diskette object is selected, either as a window or as an icon, 

Eject will eject that diskette. All objects on the desktop which live on the 
diskette being ejected will animate to the diskette, cleaning the desktop of 
all objects except for the diskette object itself. When the diskette is actually 
ejected, the icon is grayed out, indicating that it is currently off-line. 

If there is still another diskette on-line, the Finder will switch to it as the 
primary diskette which owns the desktop — whan this occurs, files and folders 
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on that diskette which were marked to live on the desktop will appear, .animating 
out from the diskette icon to the desktop* If there are no on-line diskettes, 
the Finder will not allow any operations on any objects, including the off-line 
diskettes which are still displayed* When a new diskette is inserted, the Finder 
will switch to that one as the primary diskette, and re-load the desktop with the 
objects which live there* 

Note that when a diskette is ejected, an off-line image remains, as long 
as the Finder is running. (When an application is started, or the Macintosh 
is turned off, all knowledge of off-line diskettes goes away*) The off-line 
diskettes may be opened for inspection, and the folders opened, but the objects 
may not be dragged around* This is another convenience feature, which allows 
the user to inspect and compare multiple diskettes which are not necessarily all 
on-line* Also, this provides destinations for diskette-to-diskette file copies. 


The Arrangement Menu 


{ Maybe the Arrangment menu should be the Arrange menu? } 

For folder and diskette windows, the contents may be viewed in three 
different ways* Pictorial shows the contents of the window as icons, just 
as they are shown on the desk* The objects may be dragged around, selected, 
and operated on as they are on the desk* Alphabetical lists the objects 
alphabetically, with creation and modification dates for file objects* 
Chronological lists the objects in chronological order, by creation date. Non- 
file objects, such as folders, are listed at the end. 

Clean Up cleans up the desktop or the selected window by arranging the 
icons in a checkerboard grid* The objects animate from their old positions 
to the n^w, gridded positions one by one* 




Operations which occur by Dragging 


Dragging around objects on the Finder desktop may cause actions to occur* 
Some actions result in logical grouping of files and other objects, and others 
actually cause an I/O operation (such as a file copy), the modification of a 
resource file, or the launching of an application* 
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Arranging Spatially 


Objects may be dragged on the desktop or in a window. Objects may overlap 
slightly, but an entire overlap would be interpreted as an attempt to drop the 
object on top into the one underneath. Scrolling in a window is done as explained 
earlier, but objects which are dragged outside of the window do not cause 
auto-scroll. 


Grouping in Folders and on the Desktop 


Any objects, other than diskette objects, may be dragged into a folder, 
by either dropping on the closed icon or by dragging into the folder window. 

This is a convenience feature, allowing the user to group related objects in a 
simple way. The files aren't changed in any way, and the directory structure 
is unchanged. 

The desktop is conceptually a folder also, and objects may be dragged to 
the desktop for immediate access. Typically the user would arrange his or her 
favorite working files and/or applications on the desktop, so that it would not 
be necessary to open the diskette object to access them. This allows the user 
to "flatten the hierarchy" to get direct access to the files and other objects 
which are frequently used. Other objects, such as files out on the network, 
may be grought to the desktop. The Finder will maintain a path for such objects 
so that any access to the object will use the correct device. A special attribute 
of the desktop is that it always contains the diskette objects (both on-line 
and off-line) while the Finder is running, as well as the waste basket and the 
clipboard. 


Copying Files and Diskettes 


Diskettes are copied either by selecting the diskette, choosing Duplicate 
in the File menu, and following the instructions in the Dialog box for swapping 
the diskettes, or by dragging one diskette on top of the other. In the case 
that there is only one drive, the Finder will lead the user through the diskette 
changes necessary. If there are two on-line diskettes, dropping one diskette 
onto the other will result in an alert box which allows cancellation of the 
operation; the copy will occur if the OK box is selected in the alert. In either 
case, Duplicate will cause the user to swap diskettes, since there is no 
destination specified for the duplicate diskette. 

If the source and destination diskettes in a copy have the same name, 
the Finder will attempt the copy by looking for distinguishing features on each 
diskette (creation date, etc.) Finally, if the Finder is not able to distinguish 
the two diskettes (if the user put back the same diskette, for example) then 
the copy does not occur, and an alert box is put up. 
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At the end of a file or diskette copy, the initial diskette is back in the 
built-in drive, and the state of the desktop is unchanged, except for the possible 
addition of a new off-line diskette. 

Files are copied simply by dragging the file to be copied from the source 
diskette to the destination diskette, which may be off-line. The destination 
diskette may either be opened into a window or closed. The Finder will 
as usual lead the user through the diskette swapping, as required. If the file 
is to be copied to the same diskette, selecting the file to copy and choosing 
the Duplicate command in the File menu will copy the file to a new file 
on the same diskette. 

Off-line diskettes may be considered exactly the same as the on-line 
diskettes, in that they are destinations for diskette or file copies. The only 
difference is that using an off-line diskette will require disk swapping by 
' the user. 

Diskettes are automatically initialized by the Finder on disk insertion, 
if necessary. The Finder will bring up an alert box which informs the user that 
the diskette has not been initialized and/or that the diskette is formatted for 
a different computer; the OK button is hilighted to inform the user that it is 
the preferred choice. 

When a diskette is inserted, an icon for that diskette appears on the desktop. 
The current selection is unchanged. If the diskette is unreadable, or the directory 
is destroyed, the Finder will attempt to repair the diskette. Again, an alert box 
s shown giving the user the choice to either attempt the repair .or to eject the 
diskette; the preferred action is to attempt to repair the diskette. 


Deleting Objects 


Objects are deleted by dragging them to the waste basket and dropping them 
in. Dropping a folder into the waste basket will delete all the files which 
are contained in the folder, as well as the folder itself. An alert box will 
precede any operation as dangerous as this. The Macintosh file system allows 
undeleting of a certain number of previously-deleted files; these files show 
up in the waste basket window when opened. The user may drag the files out o 
the waste basket back onto the desktop to undelete them. It is not guaranteed 
that files dropped in the waste basket will be saved, since the blocks that the 
files used may be re-used at any time. 

Desk accessories may not be deleted in this way. They must be deleted by using 
the Driver Resource Representative to transform the installed desk accessory into 
a fi?e, then dragging the desk accessory file to the waste basket.. { How should 
the Finder distinguish between desk accessory files which are not installed in 
the system resource file and those that are? They both might live on the desktop, 
while one is usable as a resource and may be opened and closed, and the other 
basically useless as a file only. When the user receives the Mac, there will 
be a diskette full of different desk accessories which are just files on the 
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diskette; the user needs to drag the desk accessories to the resource rep to 
install them and make them usable. I don't want the Finder to know about all 
the different kinds of resources, and I want it to be as flexible as possible... } 

Applications are handled with a little more care by the Finder. If the user 
attempts to delete an application, the diskette is checked first to see if there 
are any documents which that application created or can edit, and if the application 
being deleted is the only one which can edit the documents. If that is the case, 
an alert box comes up informing the user that deleting the application will 
"orphan" the documents — there will no longer be an application which can edit them. 
The Cancel button in the alert box is highlighted, indicating the preferred choice. 


Off-Line Objects 


{ This section is not complete. It deals with ejecting and viewing off-line 
diskettes and file objects. Since some of the issues have been discussed 
in previous sections, I feel that it is OK to send this draft out as is. 
Please let me know any ideas or any questions you have about this particular 
part of the Finder. } 


Desk Accessories, Finder-Specific Accessories, and Resource Representatives 


In the interest of being as flexible and extensible as possible, the Finder 
supports special objects on the desktop called Desk Accessories. There are three 
different kinds of accessories that the Finder deals with: normal desk accessories, 
like the calculator, clock, and puzzle; Finder-specific desk accessories, like 
the picture printer; and Resource Representatives, desk accessories which give 
access to the various different kinds of resources in a resource file (usually 
the system resource file). 


Normal Desk Accessories 


The normal desk accessories, such as the clock and the calculator, know 
nothing about their environment. The Finder does not communicate with them except 
to open and close them { the Finder must know when an accessory is being closed, 
in order to zoom it down to the icon }. When frontmost, normal desk accessories 
handle all the mouse and keyboard events until something is selected outside of 
the accessory window. 




Macintosh Software 


Apple Computer 



The Macintosh Finder 


Page 15 




Finder-Specific Desk Accessories 


Finder-specific desk accessories are desk accessories which understand 
an extended protocol with the Finder. The Finder uses this protocol to communicate 
to the desk accessory information about a possible file transaction which the 
accessory may need to handle. 

The protocol consists of the following new control calls: 

Name Arguments Function 




CanAccept Filename, Type Returns whether the driver can accept 

the filename of the given type for input# 

Accept NFiles, FNamel#.# "Accepts" the given file or files to 

(list of pointers) to process. For example, the picture 

printer will take a file of type PICT 
and print it on the output device. 

{ Need other protocol for dragging OUT of a desk accessory... } 


These desk accessories are always Open, in the driver sense, though they 
might or might not show a window. This is to allow the Finder to send the control 
calls to the accessory while the window is not open. For example, the picture 
printer will typically be closed into its icon, though it will accept files 
dropped on it to be printed. 

If the Desk Accessory is a printer driver or some other device driver, its 
window might display the spooled files waiting to be printed, the progress of 
the currently printing file, printing speed, and any special modes which are 
in effect. This information would most likely come, from the printer driver 
in RAM, but in the case of an I/O device on the network it might be retrieved 
from the device itself. 


Resource Representatives 

r 


Resource Representatives are special Finder— specif ic desk ornaments which 
access and modify resources in any resource file, though usually the system 
resource file is the one being accessed. 

Resources are identified by a four-byte resource type ("ICON", "PICT" , and 
so on) and either a name or an integer ID. Resources are kept in special 
resource files, either the system resource file or a resource file which is 
attached to an application or document. All resource files are invisible to the 
user from the view of the Finder. 
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Most resources are too complicated for the Finder to add, change or modify 
even with the use of a resource representative. Though a resource representative 
can handle any kind of resource, most kinds are not appropriate to change from 
the Finder. These resources are modified with the use of a special-purpose 
application called the Resource Editor. Examples of these types of resources 
include menus, dialogs, controls, and windows. Some resources, however, are of 
general enough interest that it is convenient to install and modify them from 
the Finder. These include fonts, other desk ornaments, and pictures. 

Dragging a file into a resource representative installs that file as a 
resource with the given type. Of course, the user must drag font files into the 
font representative and picture files into the picture representative; if the 
file type does not correspond to the type of resource representative, the 
operation does not take place. In some cases additional information is needed 
to fully install the resource in the resource file; in most cases, the user 
will need to also supply an ID for that resource — the resource representative 
will set a dummy ID (9999, for example) which can be edited later. Drivers 
and desk ornaments, when they are installed, use the same name as a resource 
as they did as a file, so no additional information is needed. 

From the open resource representative window, the user may see all the 
different resources of that type in the file by. scrolling up and down through 
the file. Editing of the resource names and ID f s is supported, and some 
representatives may allow limited editing of the resource itself. In a pane at 
the top the user may specify which resource file the representative points to; 
the default is the system resource file. 

Resources may be dragged out of a resource representative , .which results 
in the resource being copied to a separate file of the same type (for example, 
PICT), and deleted from the resource file. The name of the newly-created file 
is the same as that of the resource, if the. resource was named, or constructed 
by appending the ID of the resource to the type (i.e. PICT67). { The way 
resource representatives allow dragging out is still being discussed. } 


♦ 

Implementation Notes 


The Finder is implemented with the help of the resource manager. All 
objects which are manipulated by the Finder are resource objects with the 
following structure: 


FinderObject* 




RECORD 




name : 

STRING [15] 

9 

{ Will be a string handle } 

kind : 

ResType; 


{ FLDR, for example } 

location : 

Point ; 



IconID: 

INTEGER; 



view : 

INTEGER; 

{ 

selected, grayed, window, etc. 

home : 

FOHandle ; 

{ 

FinderObject Handle } 

std Info : 

Longlnt ; 

{ 

special info for each kind } 

wind : 

WindowPtr ; 
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windRect : 
nSublteras : 
subList : 


END; 


Rect; { to remember where to put new window } 

INTEGER; 

PACKED ARRAY [1.. 64 { NSubltems, really }] OF 
RECORD 

objType: ResType; 

objHandle : FOHandle ; 

END; 


The subList is used to hold sub— items of a given object# For a disk object 
the subList contains file and folder objects, for example# 

There are several resource types which are used internally by the Finder# 
These are objects of type DISK, FLDR, WSTE (the waste basket), and SCRP (the 
scrap). Other resource types used internally as well as externally include APPL 
(application), DRVR (drivers and desk accessories), ICON (icons), PAT and PAT// 
(patterns and pattern lists), and PICT (QuickDraw pictures). 

These resources are kept in a resource file called Desktop# The state of 
the desktop, the folder contents, object locations on the "file plane," and 
so on is kept in the resources themselves# 

The various icons that are displayed in the Finder are also stored in the 
Desktop resource. When a file is first copied to a diskette, the Finder 
extracts its icon out of the resource fork of the file, makes a copy of it 
in the Desktop resource, and sets the ID in the resource object which represents 
that file# In this way it is only necessary to have one resource file 
(besides the Finder f s own) open while the Finder is running# When the file 
is deleted, its icon is deleted out of the Desktop resource# Since many files 
w ill have the same icon, the Finder will compare any new icons with the already- 
existing icons in the Desktop resource# If there is already a copy, the icon will 
not be added to the resource file and the ID will be set as usual in the file 
object. 


When a diskette is inserted, the folder and file information for that diskette 
is read from the Desktop resource file for that diskette and resource objects 
created for use in RAM#* If there is no such resource file, a resource object 
is created for each file on the diskette by the Finder, and locations, etc# 
are set to default values# When the diskette is ejected, any new information 
or changes to the desktop for that diskette is written out to a new Desktop resource 
on that file# 


If a diskette which was previously off-line is re-inserted, a consistency 
check is done to see if the information which is kept for that diskette in RAM 
is still correct# New files which have appeared on the diskette since it was 
last inserted (added by a friend with another Macintosh, for example) are noted 
and objects created# Any resource objects which do not correspond to files 
or objects on the diskette are of course deleted# 

Each file on the diskette has some information stored in the user-definable 
field in the directory. There is a four-byte Resource Type (PICT, APPL, etc.) 
followed by a four-byte Signature, which uniquely identifies the creator of 
the file. For example, a MacSketch document might have type MBTS (for macSketch 
bits) with signature BAMS (Bill Atkinson MacSketch). Of course, the types 


Apple Computer 


Macintosh Software 



The Macintosh Finder 


Page 18 




and signatures do not need to mean anything, but by convention they have some 
identifiable ASCII appearance whenever possible. 

The application is responsible for setting these bytes when it creates a file 
by calling the procedure SetFinderlnfo, available in OSMisc (MacMisc). The 
parameters to SetFinderlnfo are just the type and signature: 

PROCEDURE SetFinderlnf o( theType , theSignature : ResType); 

There is also a procedure to return the current type and signature of a file: 

PROCEDURE Ge t Finder Inf o( VAR theType, theSignature: ResType); 

The signature allows the Finder to know what application to run when 
a document is opened. Since the signature is linked only to the application 
and not to a diskette, the application may be on a different diskette than 
the document (in a two-drive system). Some applications may be able to accept 
(and write out) several different types of documents. The signature idea allows 
multiple types of files to point to the same application to run when opened. 

Since the "point-and— go 11 feature may be overridden by selecting a document 
and an application to run, some applications may want to change the signature 
which is already set for the document. This should be done carefully. 
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Loading and Printing Documents from the Finder: 

The format of the AppParmHandle has changed. The new format Is 
as follows: 

Message (2 bytes): 0 * Load. 1 * Print. The Print message is 
sent when the Print item is selected in the Finder. 

Count (2 bytes): number of documents which follow. 

FOR I:= i to Count: 

VRefNum (2 bytes): volume refnum on which file exists. 

Type (4 byte resType) of document l.e. PNTG. 

VByte (2 bytes): high order byte of word is the file's 
version byte. This is typically zero. 

Name (1+strlen): Pascal string of filename. There is no 

volume prefix. The string is padded so that the 
next document entry starts on an even boundary. 


To load a' document or documents, the application walks through 
the appParmHandle structure to get each file's type, volume, vbyte and 
name. If a file Is of an unknown type, the application may want to 
open it anyway and see if it really Is of a compatable type by checking 
an internal structure. 

Printing a document is handled in exactly the same way. though 
the document is only printed. It is much nicer if the application 
doesn't do its entire start-up sequence when printing. For example, it 
may not be necessary to show the menu bar or document windows, and 
loading the scrap is definitely not required. 

When a document Is successfully printed, the application should inform 
the Finder of this by clearing out the Type field In the AppParmHandle 
entry for the given document. If the application was NOT able to print 
it. it should not clear the field— when the Finder restarts it will launch 
that document's creator to print. In this way the Finder can handle 
printing of many different types of documents in a single stream. 



Exporting Types and Icons: 

Each application has a unique Signature and it may export unique 
file Types. A clearinghouse will exist for allocation of these identifiers. 

In addition, the application may have one or more icons which it will 
want displayed for the application itself and for each of the different 
file types it may create. The IDs of the icons and file type resources 
are arbitrated at runtime by the Finder and need not be unique. 

In the application's resource file is a representative of the 
application Itself, called the 'autograph.* The type of this resource is 
the same as the signature of the application, and the ID is always 0 by 
convention. This may be aliased to any type, though typically it is 
equivalent to a STR (Pascal string) and can be used for version control. 
The autograph owns a Bundle which is the transport and Indirection 
mechanism for exporting the types and icons. 

In the applications resource file are one or more FREF resources. 
These resources have the following format: 

TYPE (4 byte resType) 

Local Icon ID for display in the Finder (2 bytes) 

Name of file (Pascal string) 

Thes FREFs provide a mapping between a file type, such as APPL 
or PNTG. and an icon, as well as a filename for any files which are 
logically part of the application and would need to be moved with the 
application during a file copy. If the particular FREF is only defining a 
file type and corresponding icon, the filename will be empty. 

The application's icons are stored in the resource file as well. 
Since the icons must include a mask for display in the Finder, a special 
type. ICN*. an icon list, is used. In this degenerate case there are only 
two icons in the list where the first 128 bytes is the data, and the 
second 128 bytes is the mask. 

Finally, a Bundle which groups these separate resources together is 
needed. The bundle provides a mapping between local and global ID s of 
the different resources. The bundle is logically owned by the 
'autograph* resource, and it is copied along with the autograph when 
installing the application, represented by the autograph in the Desktop 
resource file. When the resources are copied to Desktop the global IDs 
may need to be changed to avoid conflict, while the local IDs are not. 



The Finder locates the icons and FREFs by making an indirect reference 
through the Bundle to find the actual Global ID's of the resources. 

All applications must have autographs in their resource riles. It 
is not necessary for applications which do not export either icons or 
types to have the bundle. FREF s or ICN*‘s. since the Finder will just use 
the generic application and document icons when displaying the files. 

MacPaint, whose signature is MPNT and who exports the file type 
PNTG would have the following definitions in the resource file. Type 
TEMP and the file MyTagAlong are Included for the sake of the 
example, and are not actually used by MacPaint. 


* First, the 'autograph* 

Type MPNT - STR 

.0 

MacPaint Version 1.0— 20 November 1983 

-Now the FREFs for APPL PNTG. and TEMPrespectively. The IDs start 
-at 128 because IDs below 128 are used to refer to global & system 
-resources. Comments in 1 1 should not be typed into the resource file. 

Type FREF 
.128 

APPL 0 I 0 means use local icon 0 for the application I 
.129 

PNTG 1 I 1 means use local Icon 1 for any PNTG file I 
.130 

TEMP 1 MyTagAlong 

I icon 1 for any TEMP, and bring MyTagAlong when copying 1 

-Now the ICN*. the icons. The first 128 bytes are the Icon itself, and 
-the second 128 bytes are the mask. 

Type ICN* * HEXA 
- The application icon and mask: 

.L28 (32) 

00010000 

00028000 

... (32 rows of the application icon) 

00010000 

00038000 

...(32 rows of the application mask) 



* The MacPaint document icon and mask 
.129(32) 

OFFFFEOO 

08000300 

...(32 rows of the document icon) 

OFFFFEOO 

0FFFFF00 

..(32 rows of the document mask) 

"Finally the Bundle that brings them all together 


TYPE BNDL 
.128 (32) 
MPNTO 
ICN* 

0 128 
1 129 

FREF 
0 128 
1 129 


I the owner Is the 'autograph* string I 
I the following are ICN* references! 

I local ID 0 maps to global ID 128 I 

I single CR terminates type list within a bundle ) 
I the following are FREF references I 


I two CR's terminate the bundle Itself. I 




With these definitions in the resource file, the Finder will: 

—Display files with signature MPNT and type APPL. PNTG or TEMP 
with the appropriate Icons; 

—Copy MyTagAlong file whenever MacPaint Is being transferred to 
another disk. 

Applications which modify or create documents of an already 
existing type should use the same type and signature as the original 
application. For example, a program that merges two MacPaint 
documents into a single document would use the same type. PNTG. and 
signature MPNT as MacPaint. 

Since the Finder uses both the signature and the type of a file In 
determining what icon to display, other applications may export the 
same types but assign different icons to them. For example, if another 



program with signature DWIM creates a file with type PNTG. the icon 
used wlii be the one defined in the DWIM resource file, if any. In the 
case that there is no icon defined for that type with signature DWIM. 
the Finder currently will NOT default the icon to the one defined by 
MacPaint, though this may change. 


There will be 
special types FREF 
HEXA to implement 

Type FREF - HEXA 
.128 (32) 

4150504C I 

0000 I 

00 I 

Type BNDL - HEXA 
.128 (32) 

4D504E54 0000 I 

0001 I 
49434E23 0001 I 

0000 0080 I 

0001 0081 I 

46324346 0001 I 

0000 0080 I 

0001 0081 I 


new version of RMaker which will implement the 
and BNDL soon. In the interim, you may use type 
the two special types. For example: 


this is APPLI 
use local icon 0 I 
no filename I 


MPNT 0 is the bundle owner I 
2 types in the bundle (zero based) I 
2 ICN* entries I 

local ID 0 maps to global ID 128 I 
local ID 1 maps to global ID 129 I 
2 FREF s as well I 
local ID 0 maps to global ID 128 I 
local ID 1 maps to global ID 129 I 


« 
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To: All Developers 

From: Mac Technical Support 

Re: Important Changes to the Finder 


Please note these important di fferences in the December 4 Finder -from previous 
versions: 

- To launch any application that doess not have the -file type set, hold down 
the Feature (Command) key and double click on that appl i cat i on's icon. 

- To assign an icon to a document or application, special resource -file 
de-finitions are required. This information is -forthcoming. 

- The Finder does a reasonably good job of dual and single drive copies, but 
it does not know how to put down boot blocks yet. The application D1SKUT1L 
also does not put down the current correct boot blocks. Use WRJTEBOOT to 
place the correct boot blocks on a disk. 

- The file STARTUP is the part of SYSTEM that is only referenced at boot 
time. This file is required on all bootable disks. 

- You may use the SETFINFO (Set File Type) program to set an Appl i cat ion's 
file type to APPL. This will allow the Finder to identify this file as 

an executable program. This allows the Finder to pretend that the 
necessary resource definitions, mentioned above, are in place. The penalty 
is that the Finder must install the necessary file information in the 
system file DESKTOP each time the Finder starts up. It may be more 
convenient just to hold down the Feature (Command) Key and double-click the 
icon to start the application. 



About the Example Programs 

Once these programs are installed, you may examine all of the example -files in 
the Editor. The example -files are in the MISC: volume and their -filenames end 
in .TEXT. Each example program consists o-f three -files. The Pascal sources are 
EDIT, FILE, and GROW. The associated resource definition files are EDITRESDEF , 
FILERESDEF and GROURESDEF. The files E.TEXT , F.TEXT and G.TEXT are exec files 
which will build an application program. 

The EDIT sample program is the simplest. GROW adds a variable-sized window and 
scroll bars to EDIT. FILE adds multiple windows and simple file I/O to EDIT. 

To try out an exec file, connect the Mac and Lisa with one of the supplied Mac 
printer cables. Connect each end to the leftmost serial port, with the front of 
the machine facing you. Boot the Mac Master diskette. Double click on the di 
icon labeled 'Disk Utility.' <0n older release disks, it may be labeled 
'NewestUt i 1 . ' ) Click on the GET FILE button on the left side. From the Lisa 
command line, type XMISC:E <to execute the EDIT exec file) and press RETURN. 

The exec file will compile the program EDIT into intermediate code, generate 
68000 code, and link in runtime segments. Next, it will execute the program 
RMAKER, which in turn compiles EDITRESDEF, and links the code segments to the 
resource definitions. Then, it will execute the program SENDONE, which 
transmits the complete load module to the Mac. If the transmission is 
successful, several temporary intermediate files will be removed from the MISCs 
directory. 

To run the transmitted program on the Mac, pull down the Utility menu and select 
Exit. From the finder, hold down the Feature (Command) key and double-click on 
the document labeled EDIT to launch this program. 

Eventually, much of this information will appear in a more organized form in the 
'Putting Together a Mac Application' document. 




12/12/83 


Read Me First 


11 



CHANGESEG . OBJ 

28-Mar -83 

change segment name 

CHANGETRAP . OBJ 

8-Mar-83 

change trap handler (no Mac application) 

C0DES1ZE.0BJ 

8-Mar -83 

size of code segments 

DIFF.OBJ 

14-Apr-83 

text f.ile differences 

DUMPHEX.08J 

8-Mar-83 

hexadecimal dump 

DUMPO . OBJ 

10-Jun-81 

limited procedure oriented dump 

DUMPOBJ . OBJ 

28-Mar-83 

disassembler 

FILEDIV.OBJ 

25-Feb-82 

divides a f i le 

FILE JO IN. OBJ 

25-Feb-82 

joins two or more files 

FINDID.OBJ 

8-Mar-83 

find Pascal substrings 

FI NOWORD. OBJ 

8-Mar -83 

find Hex values 

GXREF.OBJ 

14-Apr-83 

global cross reference 

OB JD IFF. OBJ 

16-Apr-83 

object file compare 

PATCH. OBJ 

8-Mar -83 

hard offset patch utility 

SEGMAP . OBJ 

8-Mar-83 

segment map 

SETS I 2 ES. OBJ 

18-Mar -83 

set sizes of heap and stack (no Mac application) 

The following files are sample applications and programming examples: 

Program Name 

Date New 

Comments (also 'About the Example Pgms.,' below) 


ADESKACC .TEXT 6 - Ju 1 -83 

E. TEXT 27-0ct-83 
EDIT. TEXT 27-0ct-83 
EDITRESDEF .TEXT 27-0ct-83 

F. TEXT 27-0ct-83 
FILE. TEXT 27-0ct-83 
FILERESDEF.TEXT 27-0ct-83 

G. TEXT 27-0ct-83 
GROW. TEXT 27-0ct-83 
GROWRESDEF .TEXT 27-0ct-83 


a sample desk accessor/ (assembly) 

EDIT's exec -file 

the Pascal source to EDIT 

the resource definition for EDIT 

FILE'S exec file 

the Pascal source to FILE 

the resource definition for FILE 

GRQU's exec file 

the Pascal source to BROW 

the resource definition for GROU 


The LisaTalk program allows you to receive a file transmitted by the Mac 
resident MACTALK program. 


Program Name Date 


New Comments 


LISATALK. TEXT 2?-0ct-83 
STRIPPER. TEXT 9-Nov-83 


For now, use this utility to receive, only 
* A utility to remove the extra transmitted block 


The following files are useful for experienced programmers who wish to know more 
about the standard file package. This package is not yet documented outside of 
these files. See additional comments above. 

Program Name Date New Comments 


STDTEST.TEXT 
STDRESDEF .TEXT 
SF.OBJ 
SF.TEXT 


* cal 1 ed MFTEST.TEXT in the comment exec file 

* called TEXTRES.TEXT in the comment exec file 

* the standard file package object 

* the standard file package source 
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references unnecessary units such as 


PONG and SCRAMBLE. Ignore these. 


*** 


About the Files on the. OBJ: Volume 

Most of the files on the OBJ: volume are machine readable versions of the human 
readable 1NTRFC: Pascal interfaces. These files are described in text form 
above. The files below are linked with your application: 


Program Name Date New Comments 


CE.OBJ 25-Gc t-83 
MA CM I SC. OBJ 8-Jun-83 
MACPASL1B.0BJ 8-Dec-83 
MEMT RAPS. OBJ 8-Nov-83 
TOOLTRAPS.OBJ 7-Sep-83 
STDFILE68K.Q8J 2-0ct-83 
ELEMSASM.OBJ 1 -Nov-83 
SANEASM . OBJ 1 -Nov -83 
PRL1NK.0BJ <4 -Nov-83 


CoreEdit routines 
Miscellaneous Mac routines 
* Pascal routines like MOD and BLOCKREAD 
Memory Manager "glue* 

Pascal Tool Box trap table 

The standard file package "glue“ 

The floating point package "glue* 

The 'SANE' numerics package "glue* 

The printing package 'glue* 




About the Files on the TLASM: Volume 


These files are predeclared sources for assembly language programmers. 


Program Name 

Date 

New 

Comments 

DISKEQU.TEXT 

l?-0ct-83 


disk drive equates <was called SQNYEQUeTEXT) 

FSEQU.TEXT 

?-Nov-83 

* 

file system equates 

GRAFEQU .TEXT 

20 -Aug-83 


QuickDraw equates 

GRAFTYPES .TEXT 

30 -May-83 


QuickDraw structures 

HEAPDEFS.TEXT 

7-Dec-83 

* 

the system heap 

PREQU.TEXT 

25-Ju 1 -83 

* 

printer equates 

QUICKMACS .TEXT 

14-0ct-83 

* 

QuickDraw entry macros 

RESEQU.TEXT 

2-Sep-83 


resource equates 

SAN EMACS. TEXT 

1 -Nov -83 


SANE numerics macros 

SYSEQU.TEXT 

6-Dec-83 

* 

system equates 

SYSERR.TEXT 

24-0ct-83 

* 

system errors 

SYSMACS .TEXT 

2?-Nov-83 

* 

system macros 

TOOLEQU .TEXT 

11 -Sep-83 


Tool Box equates 

TOOLMACS.TEXT 

4-Sep-83 


Tool Box entry macros 


About the 

Files on the MI SC: Volume 


These files are examples and utilities which are generally not required in the 
course of application development but may be needed in some special cases. 

The following files are Lisa utilities that manipulate source or object files: 


Program Name Date New Comments 

BYTEDIFF .OBJ 28-Mar -83 hex file comparison 
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About the Files on the LISA: Volume 


Most of the tiles on the LISA: volume are used by the system in response to 
commands like C(ompi1e or E<dit. A tew are directly executed by the user and 
are spec it ic to the Macintosh development environment. 


Program Name Date New Comments 


RMAKER.QBJ 27-0ct-83 
SENDONE . OBJ 27-Aug-83 
SENDFILE.OBJ 29-Aug-83 


The resource compiler 
A utility to transmit a single tile 
A utility to transmit multiple tiles 


RMAKER is discussed at length in 'Putting Together a Mac Application.” *** This 
document is currently under revision to coincide with the current development 
environment. *** 


About the Files on the INTRFC: Volume 

The tiles on this volume are Pascal interfaces to various ROM or RAM based 
pieces of the Tool Box. 


Program Name 

Date New 

Commen t s 

COREEDIT. TEXT 

1 -Jan-80 

See 

•CoreEdit” 

ELEMS.TEXT 

17-Nov-83 

See 

•Summary of FP48K Documents 

GRAF UTIL. TEXT 

16~Feb-83 

See 

•Tool Box Utilities* 

HEAP 2 ONE .TEXT 

7-0ct-83 

See 

•Memory Manager* 

MACCMGR.TEXT 

7-0ct-83 

See 

•Control Manager* 

MAC DMGR. TEXT 

13-Sep-83 

See 

•Dialogue Manager* 

MACDSKMGR .TEXT 

7 -Oct -83 

See 

“Desk Manager “ 

MACEMGR.TEXT 

7-0ct-83 

See 

“Event Manager* 

MACFMGR.TEXT 

3-Jun-83 

See 

•Font Manager" 

MACMMGR .TEXT 

7-0ct-83 

See 

"Menu Manager* 

MACPRINT.TEXT 

25-Jul-83 

See 

•The MacPrint Interface" 

MACRM6R.TEXT 

15-Sep-83 

See 

•Resource Manager* 

MACSMGR .TEXT 

8-Sep-83 

See 

•Scrap Manager* 

MACMMGR. TEXT 

7-0ct-83 

See 

•Window Manager" 

OSMISC .TEXT 

4-May-83 

See 

*0S Reference" 

QUICKDRAW. TEXT 

27-0ct-83 

See 

•QuickDraw* 

QUI CKDRAU2 .TEXT 

27-0ct-83 

part 

2 of QUICKDRAW. TEXT 

SANE .TEXT 

1 -Nov -83 

See 

“Summary of FP68K Documents 

STOFILE.TEXT 

19-Sep-83 

#** 

see note below *** 

TEXTEDIT. TEXT 

13-Jul -83 

See 

•TextEdit* 


The Standard File package allows your application program to present the user 
with a choice of all applicable data files. It is presently undocumented. 
Those ambitious enough to use it without documentation are recommended to 
study the example program "STDTEST" and its resource file "STDTESTREF” on the 
MISC: volume, as well as the Pascal interface on the INTRFC: volume. An 
assembly programmer wishing to use the Standard File package will have to mock 
up a Pascal interface for that purpose. **# NOTE: the example program 
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-files that you are interested on this disk. 

In actual program development, you would use the SENDQNE program 
instead of the SENDFILE program inside an exec -file to transfer the 
program. The steps are described in 'About the Example Programs', 
below. 


About the files on the MACs Volume 


In addition to the sample program files, a number of system files and utilities 
are provided on the Mac: Volume. These may be transmitted and then used on 
the Mac: itself. They are: 


Program Name 


Date 


New Comments 




ADEOIT.RSRC 
BOOTCONF I G . RSRC 
DESKTOP. RSRC 
DISASSEMBLER 
D1SKUTIL.RSRC 
EDIT. RSRC 
FILE. RSRC 
FINDER. RSRC 
FONTEDITOR . RSRC 
FONTS. RSRC 
GROW. RSRC 
I CONED IT. RSRC 
1MAGEURITE . RSRC 
MACSBUG 
MACTALK . RSRC 
MACTERM.RSRC 
PR I NT. RSRC 
RESCON. RSRC 
RM OVER. RSRC 
SETFILTYPE.RSRC 
SOUNDLAB . RSRC 
STARTUP. RSRC 
SYSTEM 
SYSTEM. RSRC 
TMACTERM . RSRC 
WRITEBOOT .RSRC 
WM6RDEM0 . RSRC 


24-0ct-83 

7- 0ct-83 

13- Dec-83 * 

14- Jun-83 
l?-0ct-83 
27-0ct-83 
27-0ct-83 

13- Dec-83 * 

14- Nov-83 * 

5-Dec-83 * 

27- 0ct-83 

28- Jun-83 

8- Dec-83 * 
31 -Aug-83 
10-Nov-83 

3- Dec-83 * 

4- Dec -83 * 

7-Sep-83 

21 -Oct -83 
12-Dec-83 * 

l?-Aug-83 

5- Dec-83 * 

9- Dec-83 * 

1 -Dec -83 * 

3- Dec-83 * 

4- Dec -83 * 

28-Jun-83 


an Alert and Dialog Box editor 
a utility to configure the disk's boot blocks 
a data file for Finder 

provides MACSBUG with nonsymbol ic disassembly 

the disk formatter and file receiving program 

a sample program (see below) 

a sample program (see below) 

you see this after you boot the master disk 

a font edi tor 

a collection of predefined fonts 
a sample program (see below) 
an icon editor 

the Imagewriter printing routines (see below) 
a nonsymbol ic debugger 
a file transmission program 
a terminal emulator application 

prints application output (was called PRAPP.Rf ) 
a utility to convert old programs (see below) 
a utility to examine and move resources 
a utility to set file types (was called SET I CON) 
a demonstation of Mac's sound capability 
system resources used only at boot time 
enhancements to the Tool Box routines 
the system resources 

a special MacTerm version for 5 1/4" Macs 
a utility to update the boot tracks (see above) 
a window manager demo 


The programs WMGRDEMO . RSRC , SOUNDLAB . RSRC and ICQNEDIT.RSRC need to be revised 
to run under the current ROMs. To bring each up to date, use the RESCON. RSRC 
program on the Mac to convert the resources of each of these files. 


The program MACTERM.RSRC will not run on a disk that contains the DISASSEMBLER. 
To use MacTerm on a disk with the debugger, rename DISASSEMBLER to a different 
file name and reboot the disk. 


The resource IMAGEUR1TE.RSRC should be renamed IMAGEWRITER when transmitted to 
the Mac to allow printing to function properly. 
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Fran the Lisa Command line, type XSENDFILE and press RETURN. 

Using the mouse, click on the box marked Volume. A blinking circle 
will appear. Type MAC: and press RETURN. 

Next, click on the box marked Pattern. Type » and press RETURN. 

Point to and click on the -following files: 

DESKTOP. RSRC 
DISKUTIl.RSRC 
FINDER. RSRC 
STARTUP. RSRC 
SYSTEM 
SYSTEM. RSRC 

These are the minimum files you can put on a new disk, and be able to 
use i t as an application work disk. 

On the Mac, boot one of the master disks provided to you. Double 
click on the icon labeled 'Disk Utility 7 to launch this program. 

Click on the left button labeled "eject disk". Remove the master and 
put it in a safe place. 

Place one of the unlabeled diskettes into the drive. The Mac will 
attempt to mount the disk. For an uninitialized disk, you should see 
the words "Unmounted Volume" in the box labeled "Internal". 

Select "format disk". The format and verification process will take 
about a minute. Notes should say 'Disk Successfully Formatted!'. 

Select "get file". The notes box should say "Waiting for Header...". 

On the Lisa, select "Send It". Each file will be serially transmitted 
from the Lisa to the Mac. 

On the Lisa, quit the SENDONE program. On the Mac, the Notes box 
should say "Flushing Volume (Bye)". Press the programmer's switch 
labeled "Reset". It is the one closest to you. 

The newly created disk should boot. Open the disk icon by double 
clicking on it. The files DISKUTIL, FINDER, DESKTOP and SYSTEM will 
appear. Click on DISKUTIL to select it. 

*#* If your keyboard does not function, you may not have the current 
boot blocks on your disk. The interim program WRITEBOOT will correct 
this problem. Download this program to the Mac, then execute it by 
holding down the Feature (Command) key and double-clicking on the 
icon. After you reboot the diskette, the keyboard should work 
properly. #»* 

You should now be able to run DISKUTIL holding down the Feature 
(Command) key and double-cl i eking on the icon. Surprise! It is the 
same as "Disk Utility". Now you can repeat the process to put the 
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utilities, listed below under “About the MISC: Volume," which may be 
presently resident on the USAs volume. 


About the Disk Labeled MWUTIL 

The disk labeled MONUTIL contains Lisa-based utilities that are described in the 
Monitor documentation, and Mac application programming examples. , 

It you are updating an existing development system, you may want to 
crunch or zero the system volumes as discussed above. This exec -file 
is not destructive and will not remove or alter any -files or volumes 
other than the -files that are updated. 

To install the contents ot MONUTIL tor the tirst time, or to update your ^ 

existing ProFi le: 

Insert the disk in Drive 2. Then trom the command line, type 
X«c2/#3:D0IT and press RETURN. 

MONUTIL contains example programs and packages, such as tiles required tor 
printing, tloating point, and tile selection. 

For assembly, language programmers: 

The tile MOCPASLIB.TEXT is a mockup ot the Pascal Library. This can 
linked to or incorporated into an assembly source to allow the 
assembly program to look like a Pascal program. In this application, 
MACPASLIB.OBJ is no longer required. 

A empty Pascal program shell launches the assembly. It should look likes 
Program Dummy; 

Uses {$U Obj : QuickDraw) Quickdraw; 

Var global : array [l..xl ot integer; 

Procedure MyAssembly; External; 

Begin 

MyAssembl y 
End. 

r 

Overhead imposed by the Pascal system is reduced to a tew dozen bytes. The 
QuickDraw declaration provides tor the global variables that QuickDraw declares. 

In this program, 'x' is replaced by the required number ot words to be reserved 
as global data, which is accessed by indexing negatively ott A3. 


Creating a New Mac Master Disk 

The tiles on the hWC: volume can be transmitted to the Mac with the programs 
SENDONE and SENDFILE. Use SENDF1LE to transmit a disk tu 11 ot tiles. 

*** Executing SENDFILE atter compiling trequently causes the Lisa to reboot. 
It this occurs, just execute SENDFILE again. *** To build a new diskette: 


12/12/83 


Read Me First 


5 



Transfer any files you may have placed. for your use in the LISA: 
volume to a different volume. 

Zero the LISA: volume. 

Transfer all files from the Monitor 12.2 Boot disk to the LISA: 
volume. 

From the System Manager, set the working device to the ProFile. <&3 
for the built-in parallel port) 


About the Disk Labeled RQM7S 

The disk labeled RQM7S contains all of the special programs, code files, and 
text sources unique to Mac. 

If you already have the Monitor installed: 

The most recent revisions to the ToolBox are incompatable with 
Twiggy-based Macs. If you still have a Twiggy based machine, please 
contact us. 

If you are updating an existing development system, you may want to 
clear the system volumes to provide adaquate space for the files that 
will be transfered by the exec file. You are able to zero the 
INTRFC:, TLASM:, MAC:, OBJ:, and MISC: volumes and rebuild them from 
the R0M7S: and MONUTIL: disks. The update process is not 
destructive and will not remove or alter any files or volumes other 
than the files that are updated, but without adaquate free space on 
each volume, the transfer may not be sucessful . 

To install these files for the first time, or to update the existing files 
already installed on your ProFile: 

Place the disk labeled R0M7S in Drive 2. From the command line, type 
X*2/tt9:D0IT and press RETURN. 

(If, for some reason, you are not already at the command line, you may 
get there by pressing the key on the numeric keypad, typing RM and 
pressing RETURN.) 

This exec file will install all unit interfaces and code segments 
needed to develop Mac software. It will take about 15 minutes. 


For existing Monitor users: 

You may also find that you do not have adequate space on the LISA: 
volume to contain all of the needed system files, SENDONE.OBJ, and 
SENDFILE.OBJ. To free up additional space on the LISA: volume, 
either zero and reconstruct it as shown above, or move the standalone 
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The Monitor development system you will create or update is divided into nine 
volumes. At present , these volumes are named as shown: 


Volume Name Contains 


LISA: 

OBJ: 

TLASM: 

INTRFC: 

WORK: 

BACK: 

RSRC: 

MC: 

Ml SC: 


all required Pascal and Operating System •files 

machine readable interface and linker code files 

assembly source files 

human readable Pascal unit interfaces 

your work files 

a backup copy of your work files 
**« -This volume has no predefined purpose. *** 
files that can be transmitted to and used by the Mac 
Lisa specific utilities, and sample programs 


The Mac development software environment is distributed on three disks: 
Monitor 12.2 Boot <LISA:>, R0M7S: and MONlfT I L : . 




About the Disk labeled MCWITOR 12.2 BOOT 

The Monitor 12.2 Boot disk contains the complete Lisa development operating 
system. 

To install the Monitor development software onto a Lisa ProFile for the first 
time: 


Place your ProFile that will receive the Monitor on the built-in 
parallel port. 

Boot the disk marked: MONITOR 12.2 BOOT 

(To boot a disk in the upper Lisa drive, turn the Lisa on, and press 
Apple-1 after the single click and before the double click.) 

Once the command line appears, type XDOIT and press RETURN. 

(If the command line does not appear initially, and the screen is 
blank, start over after unplugging the ribbon cable connecting the 
ProFile to the Lisa. Then plug the ribbon cable back in after the 
command line appears. Do not turn the ProFile off.) 

An exec file will now initialize the ProFile with the Monitor 
software. This will take about a half an hour . 

After the Monitor is installed, you will still boot with the Monitor 
Boot disk. 

If you already have the Monitor installed, you will want to reconstruct the 
LISA: volume to bring your system up to version 12.2, and to make the needed 
space for additional files required by the new Mac development system. 

From the- System Manager, set the working device to the drive 
containing the Monitor 12.2 Boot disk. (41 for the upper drive.) 


12/12/83 


Read Me First 


3 



Volume 1 contains: 

Read Me First (this note) 

Inside Macintosh: A Road Map 

Index to Technical Documentation 

Macintosh User Inter-face Guidelines 

The Resource Manager: A Programmer's Guide 

QuickDraw: A Programmer's Guide 

The Font Manager: A Programmer's Guide 

The Event Manager: A Programmer's Guide 

The Window Manager: A Programmer's Guide 

Macintosh Control Manager Programmer's Guide 

Volume 2 contains: 

The Menu Manager: A Programmer's Guide 
The Dialog Manager: A Programmer's Guide 
TextEdit: A Programmer's Guide 
CoreEdit: A Programmer's Guide 
The Desk Manager: A Programmer's Guide 
The Toolbox Utilities: A Programmer's Guide 
Macintosh Operating System Reference Manual 
The Segment Loader: A Programmer's Guide 
The Scrap Manager: A Programmer's Guide 
The Memory Manager: A Programmer's Guide 
Putting Together A Macintosh Application 
Asynchronous Serial Driver 
The OS Event Manager 
Macintosh Owner's Guide 
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8/8/83 
10/5/83 
10/11/82 
10/3/83 
3/2/83 
4/22/83 
4/ 21/83 
8/25/83 
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11/1/83 
1 1/14/83 
9/28/83 
8/15/83 
9/24/83 
5/14/83 
2/28/83 
4/24/83 
10/21/83 
10/10/83 
7/14/83 
8/23/83 
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10/12/83 


Volume 3 contains: 

Welcome to Macintosh Technical Support! 
(electronic mai 1 ) 


HOW TO DOWNLOAD MACINTOSH PROGRAMS TO THE httC... 

SAD MACINTOSH ICON 

Monitor filename syntax and file structure 
S(ysmgr - System Manager 

ROM 7.0 MacsBug Summary 
Pascal Program Debug Strategy 

Pascal Reference Manual for the Lisa (029-0391-A) 
The Pascal Development System Manual pages 1 - 22 
Workshop User's Guide for the Lisa - The Assembler 
The Pascal Development System Manual pages 37 - 108 
Software Localization Guidelines 
SUMMARY OF FP48K DOCUMENTS 


Pascal Interface to the Memory Manager 
The MacPrint Interface 
Tool Box Names 


no date 
no date 
10/24/83 
no date 
no date 
no date 
no date 
no date 
2/14/82 
no date 
2/14/82 
11/10/83 
11/1/83 
9/25/83 
1 1/7/83 
7/14/83 


The first six documents should be read in the order listed. The remaining can 
be examined in any order. The order of the documents in the three binders 
may not be as listed above. 


About the Lisa Monitor Development System 
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Welcome to the Macintosh Development Environment 

These -first -few pages are important to the -first time developer as well as 
seasoned Mac developers. This is your guide to what material you have received, 
what is current, and how to make use o-f it. 

For existing developers: 

Use this guide as a checklist to make sure that you have all o-f the 
current documentation and so-ftware. Changes to the old documentation 
are noted by lines on the right side of the page. 

This guide assumes that the user is operating under Monitor 12.2 or 
equivalent, and has the following named volumes dedicated to system 
use: USA:, TLASM: , INTRFC: , OBJ:, MISC:, and MAC:. Workshop users 
must translate and recompile interfaces and examples on their own. 

If you do not have all of the following documentation, or received damaged 
media, please call Carol Ballard at 408 / 973 - 4047 to obtain a replacement. 

The new or recently modified documentation and software are marked with 
asterisks. The date listed for the software indicates the actual date of last 
change and does not necessarily coincide with the file date seen in a directory 
1 isting. 


Packing List 

You should have received the following items from Mac Technical Support: 


A Mac box containing: 

1 Mac 

1 keyboard and cable 
1 Mouse 

1 power cord • 

1 programmer's switch (a piece of tan plastic labeled 

RESET / INTERRUPT) 

2 Mac printer cables 

2 Mac 3 1/2* disk masters <put one aside to initialize blank 

disks and to create additional work disks.) 

3 blank 31/2" disks 
disk labels 

3 Lisa 5 1/4* disks 


i ^ 


To install the programmer's switch, snap it onto the left side of the Mac 
(screen facing you) at the bottom corner, toward the rear. This will position 
the plastic fingers over the internal RESET and INTERRUPT microswitches. *** 
The programmer's switch may already be in place. #** 


About the Macintosh Binders 

The Macintosh documentation is contained in three volumes. 




12/12/83 


Read Me First 


1 






MACINTOSH PUBLICATIONS 

MACINTOSH CONTROL MANAGER 

PROGRAMMER'S GUIDE 

TOOLBOX/ CONTROLS 


See also: Macintosh User Interface Guidelines 

Macintosh Operating System Reference Manual 
QuickDraw: A Programmer's Guide 

The Window Manager: A Programmer's Guide 
The Resource Manager: A Programmer's Guide 

The Event Manager: A Programmer's Guide (*** To be written ***) 




Modification History: First Draft C. Espinosa 8/13/82 

Interim release (inaccurate) C. Espinosa 9/ 7/82 
Second Draft S. Chernicoff 3/16/83 


ABSTRACT 

Controls are special objects on the Macintosh screen with which the 
user, using the mouse, can manipulate information or control the way it 
is displayed. The Macintosh Control Manager is a subroutine package, 
part of the User Interface Toolbox, that enables application programs 
to create and manipulate controls in a way that is consistent with the 
User Interface Guidelines. This document describes the program 
interface to version 2.1 of the Control Manager. 


Summary of significant changes and additions since last version: 

- Control definition functions are now treated as resources and 
accessed through the Resource Manager. 

- Control types are now identified with a control definition ID , 
which includes both the resource ID of the definition function and 
a 4-bit variation code . The variation code allows the same 
definition function to implement several related control types as 
"variations on a theme”. Built-in constants are provided for the 
definition IDs of the standard control types. 

- Templates for individual controls can be accessed as resources 
with the new function GetNewControl. 

- The contrlHilite field of a control record is now a one-byte part 
code specifying the part of the control that is highlighted. A 
code of 255 marks the control as inactive ; it is displayed on the 
screen in some distinctive way and will not respond to the mouse. 





Control records have an additional field, contrlAction, containing 
a default action procedure for use by TrackControl. There are two 
new Control Manager routines, SetCtlAction and GetCtlAction, for 
accessing this field. 

The contrlTitle field has been moved to the end of the control 
record and is now a variable-length string instead of a pointer. 
Title strings of three characters or fewer are no longer handled 
specially. 

The FindWindow function is now in the Window Manager; FindWindow 
in the Control Manager has been replaced by FindControl. 

Controls are kept in a separate linked list for each window, not a 
single list for the entire system. 

Dragging of a controls indicator with the mouse is now handled by 
TrackControl instead of DragControl. 

DragControl now takes an additional parameter, slopRect, to allow 
some "slop" in the user^s mouse movements. 

SetCtlMin and SetCtlMax now do range checking against the 
controls current setting and "pin" the setting, if necessary, to 
the new endpoint of the range. 

There are two new control messages: thumbCntl, to calculate the 
constraint parameters for dragging the indicator, and dragCntl, to 
perform custom dragging. 

The control message calcCRgns requests the indicator region 
instead of the whole controls region if the high bit of the 
parameter is set. 

The part codes used by the standard control definition functions 
have been modified and somewhat expanded; part codes > 127 (high 
bit on) now denote moving indicators. 
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ABOUT THIS MANUAL 


This manual describes version 2.1 of the Macintosh Control Manager. 

*** It will eventually become a chapter in the Macintosh User Interface 
Toolbox Programmers Guide. *** The Control Manager is the part of the 
Toolbox that deals with controls, as defined in the Macintosh User 
Interface Guidelines. Using it, your programs can create, manipulate, 
and dispose of controls in a way that is consistent with the 
Guidelines. 

(eye) 

This document applies specifically to the version of the 

Control Manager in version 2.1 of the Macintosh ROM. 

Earlier versions will not work exactly as described here. 

Like all Toolbox documentation, this document assumes you are familiar 
with the Macintosh User Interface Guidelines (particularly the section 
on controls), the Lisa Pascal programming language and system, and the 
memory management mechanism of the Macintosh Operating System. To 
understand and use the information presented here, you should also be 
familiar with: 

- The basic principles of the QuickDraw graphics package, 
particularly rectangles, regions, and graf Ports. (You don't need 
a detailed knowledge of QuickDraw, since programs that implement 
controls through the Control Manager need not interface directly 
with QuickDraw.) 

- The Window Manager. Every control you create with the Control 
Manager "belongs” to some window. The Window Manager and Control 
Manager are designed to be used together, and their structure and 
operation are parallel in many ways. 

- The Event Manager. The essence of a control is to respond to the 
user's actions with the mouse. Your program finds out about those 
actions (such as when and where the user pressed the mouse button) 
by calling the Event Manager; it can then call various Control 
Manager routines to find out whether the button was pressed inside 
a control and, if so, to respond in whatever way is appropriate. 

- The basics of the Resource Manager. You'll need this only if 
you're defining your own "custom" controls or using predefined 
templates for individual controls. If you use only controls of 
the standard types and don't create them from templates, you won't 
need to know any details about resources; the Control Manager 
itself wiil handle all dealings with the Resource Manager for you. 

It would also be helpful to have some familiarity with a Macintosh 
application program that uses controls, as an illustration of the 
concepts presented here. 

The manual begins with an introduction to the Control Manager and what 
you can do with it. It then discusses some basic concepts about 
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controls: the relationship between controls and windows; that between 

controls and resources; and how the various parts of a control are 
identified. Following this is a discussion of control records, where 
the Control Manager keeps all the information it needs about a control. 

Next, a section on using the Control Manager introduces its routines 
and tells how they fit into the flow of your application program. This 
is followed by detailed descriptions of all Control Manager procedures 
and functions, their parameters, calling protocol, effects, side 
effects, and so on. 

Following these descriptions are sections that will not be of interest 
to all readers. Special information is given for programmers who want 
to define their own controls and for those who will use the Control 
Manager routines from assembly language. 

Finally, there are a summary of the Control Manager data structures and 
routines, for quick reference, and a glossary of terms used in this 
manual. 


ABOUT THE CONTROL MANAGER 

The Control Manager is the part of the Macintosh User Interface Toolbox 
that deals with controls. A control is a special object on the 
Macintosh screen with which the user, using the mouse, can manipulate 
information or control the way it is presented. Using the Control 
Manager, your application program can: 

- Create and dispose of controls; 

- Display or hide controls on the screen; 

- Change the size, position, or appearance of a control; 

- Read or change the setting or other properties of a control; and 

- Monitor the user's operation of a control with the mouse and 
respond accordingly. 

Your program performs these actions by calling the appropriate Control 
Manager routines. The Control Manager carries out the actual 
operations, but it's up to your program to decide when, where, and how. 
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Button 1 ) 

( v Button 2") 

EJ Check Box 1 

□ Check Box 2 

□ Radio Button 1 
® Radio Button 2 
0 Radio Button 3 



Figure 1. Controls 

Controls may be of various types (see Figure 1), each with its own 
characteristic appearance on the screen and responses to the mouse. 

Each individual control has its own specific properties — such as a 
title, setting, location, and size — but controls of the same type 
behave in the same general way. 

Certain standard types of control are predefined for you by the 
Toolbox. Your program can easily create and use controls of these 
standard types; you can also define your own "custom" control types for 
your program's special needs. Among the standard control types are the 
following: 

- Buttons cause an immediate 1 or continuous action when clicked or 
pressed with the mouse. They appear on the screen as 
rounded-corner rectangles with a title centered inside. 

- Check boxes retain and display a setting, either checked (on) or 
unchecked (off); clicking with the mouse reverses the setting. On 
the screen, a check box appears as a small square with a title 
alongside it; the box is either filled in with an "X" (checked) or 
empty (unchecked). Check boxes are frequently used to control or 
modify some future action, instead of causing an immediate action 
of their own. 

- Radio buttons also retain an on-or-off setting. They're organized 
into groups, with the property that only one button in the group 
can be on at a time: clicking any button on turns off all the 
others in the group, like the buttons on a car radio. Radio 
buttons are used to offer the user a "multiple choice" among 
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several alternatives. On the screen, they look just like check 
boxes, except that the button that's on is marked with a round, 
black dot instead of an "X"* 

(hand) 

The Control Manager doesn't know which radio buttons are 
"connected” , and doesn't automatically turn one off when 
the user clicks another one on: it's up to your program 
to handle this. 

(hand) 

It's a good idea to group radio buttons visually on the 
screen to make it clear to the user which ones are 
related. Each such group should be clearly labeled 
"Choose one of the following", or something similar. 

Another important category of controls are dials . These display a 
quantitative setting or value, typically in some pseudoanalog form such 
as the position of a sliding switch, the reading on a thermometer 
scale, or the angle of a needle on a gauge; the setting may be 
displayed digitally as well. The moving part of the control that 
displays the current setting is called the indicator . A dial may allow 
the user to change its setting by dragging the indicator with the 
mouse, or it may simply display a value not under the user s direct 
control, such as the amount of free space remaining on a disk. 

The Toolbox predefines one type of dial for you: the scroll bars of 
the standard document window, which represent the visible portion of 
the document by the vertical or horizontal position of the scroll bar s 
thumb within its shaft. A scroll bar has five parts, as shown in 
Figure 2: the up and down arrows scroll the window's contents a line 
at a time, the two paging regions scroll a "page" (windowful) at a 
time, and the thumb can be dragged to any desired position within the 
document. You can define other types of dial for yourself if your 
program needs them. 
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Figure 2. Parts of a Scroll Bar 


(hand) 

The terms "up" and "down” are used even when referring to 
horizontal scroll bars. In this case, "up” really means 
"left" and "down” means "right”. 

(hand) 

Although they behave like controls, a document window's 
close box and size box are not actually implemented as 
controls, because the Window Manager can handle them with 
greater efficiency and flexibility than the Control 
Manager. 

A control may be visible or invisible . As with windows, these terms 
refer only to whether the control is drawn within its own plane. A 
control may be "visible" and still not appear on the screen, because it 
is partially or completely obscured by overlapping windows or other 
objects. Conversely, an invisible control never appears on the screen, 
even if it's completely exposed to view on the desk top. 

A visible control may or may not be highlighted . A highlighted control 
is displayed in some distinctive visual way, depending on its type (see 
Figure 3). A common way of highlighting a control is to invert it 
(change white to black and vice versa), but some control types may use 
other forms of highlighting, such as shading the control in gray or 
making its outline heavier. It's also possible for just a part of a 
control to be highlighted: for example, when the user presses the 
mouse button inside the up or down arrow of a scroll bar, the arrow 
(not the whole scroll bar) becomes highlighted until the button is 
released. 
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Figure 3. Highlighted Controls 


A control can also be active or inactive . Active controls respond to 
the user's actions with the mouse; inactive controls don t. An 
inactive control remains visible, but is highlighted in some special 
way, depending on its control type (see Figure 4). For example, an 
inactive button, check box, or radio button is "dimmed with light gray 
shading; an inactive scroll bar has no thumb. 


E? Check Box l 
03 Radio Button i 



Figure 4. Inactive Controls 
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CONTROLS AND WINDOWS 


Every control "belongs" to a particular window. When displayed, the 
control appears within that window's content region; when manipulated 
with the mouse, it acts on the contents of that window. All 
coordinates pertaining to the control (such as those describing its 
location) are expressed in its window's local coordinate system. 

(eye) 

In order for the Control Manager to draw a control 
properly, the control's window must have the top left 
corner of its boundary rectangle aligned at coordinates 
(0,0). If your program changes a window's local 
coordinate system for any reason, be sure to realign its 
top left corner at (0,0) before drawing any of its 
controls. Since almost all of the Control Manager 
routines can (at least potentially) redraw a control, the 
safest policy is simply to realign the window's top left 
corner at (0,0) before calling any Control Manager 
routine. 


CONTROLS AND RESOURCES 


Each control type has a control definition function that determines how 
controls of that type look and behave. The control definition function 
performs all those actions that differ from one control type to 
another, such as initializing or disposing of a control, drawing it on 
the screen, testing whether the mouse button has been pressed inside 
it, and responding to the user's dragging of the mouse. The Control 
Manager calls the control definition function whenever it needs to 
perform one of these type-dependent actions. 

Like menus, fonts, or icons, control definition functions are 
considered resources of your application program: they're kept in 
resource files and accessed through the Resource Manager. The system 
resource file includes definition functions for the standard control 
types (buttons, check boxes, radio buttons, and scroll bars). In most 
cases, these standard control types will be all your program will need, 
and you can just use the built-in definition functions. If you want to 
define your own, nonstandard control types, you'll have to write your 
own definition functions for them, as described later in the section 
"Defining Your Own Controls". 

When you create a control, you specify its type with a control 
definition ID , which tells the Control Manager the resource ID of the 
definition function for that control type. The Control Manager 
provides built-in constants for the definition IDs of the standard 
control types: 
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CONST PushButProc = 0; 

{simple 

button} 

CheckBoxProc = 1; 

{check 

box} 

RadioButProc = 2; 

{radio 

button} 

ScrollBarProc = 16; 

{scroll 

bar} 


(hand) 

The control definition ID includes some other information 
in addition to the resource ID of the control definition 
function. Details on this other information and how it s 
combined with the resource ID are given later under 
"Defining Your Own Controls". If you're using only the 
standard control types, you don't need to know the 
details; you can just use the predefined constants listed 
above. 

To create a new control, you have to supply not only a control 
definition ID, but also a lot of other information, such as the 
control's title (if any), the window it belongs to, its location within 
the window, and so forth. If you're creating lots of controls with the 
same general characteristics, you may want to simplify the process by 
defining a control template . This is a single resource, stored in a 
resource file, that contains all the information needed to create a 
control of a particular type. Instead of giving all the specifics 
every time you create a control, you can just supply the resource ID of 
the template. Control templates also allow you to isolate individual 
control descriptions from the code of your program itself. Then if you 
need to change the characteristics of a control — for example, to 
translate its title into a foreign language — you can just change the 
template in the resource file, instead of modifying and recompiling 
your whole program. 

(hand) 

You can create control templates and store them in 
resource files with the aid *** (eventually) *** of the 
Resource Editor. *** In the meantime, you can use the 
interim Resource Compiler; see your Macintosh software 
coordinator for more information. *** The Resource 
Editor relieves you of having to know the exact format of 
a control template, but if you're curious *** (or until 
the Resource Editor is available) ***, you'll find 
details in the section "Format of a Control Template". 


PART CODES 


Some controls, such as buttons, are simple and straightforward. Others 
can be complex objects with many parts: for example, a scroll bar has 
two scroll arrows, two paging regions, and a thumb (see Figure 2). To 
allow different parts of a control to respond to the mouse in different 
ways, many of the Control Manager routines accept a part code as a 
parameter or return one as a result. 
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A part code is an integer between (J and 255 that stands for a 
particular part of a control. Each type of control has its own set of 
part codes , assigned by the control definition function for that type. 

A simple control such as a button or check box might have just one 
"part" that encompasses the entire control; a more complex control such 
as a scroll bar can have as many parts as are needed to define how the 
control operates. Some of the Control Manager routines need to give 
special treatment to the moving indicator of a dial (such as the thumb 
of a scroll bar). To allow the Control Manager to recognize such 
indicators, they always have part codes of 128 or greater. 


The part codes for the standard control types are built into the 
Control Manager as predefined constants: 


CONST inButton 

s 

10; 

{simple button} 

inCheckBox 

s 

li; 

{check box or radio button} 

inUpButton 

3 

20; 

{up arrow of a scroll bar} 

inDownButton 

3 

21; 

{down arrow of a scroll bar} 

inPageUp 

3 

22; 

{"page up" region of a scroll bar} 

inPageDown 

3 

23; 

{"page down" region of a scroll bar} 

inThumb 

» 

129; 

{thumb of a scroll bar} 


(hand) 

Notice that the Control Manager considers a radio button 
to be a kind of check box. The part code inCheckBox 
applies to both check boxes and radio buttons. 


CONTROL RECORDS 

Every control is represented internally by a control record containing 
all pertinent information about that control. The control record 
contains: 

- A pointer to the window the control belongs to. 

- A handle to the next control in the window's control list. 

- A handle to the control definition function. 

- The control's title, if any. 

- The control's position within its window. 

- An indication of whether the control is currently visible. 

- An indication of whether the control is currently active. 

- An indication of which part of the control, if any, is currently 
highlighted. 
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For controls that retain a setting, either a simple on-or-off (such as 
a check box or radio button) or a quantitative value (such as a dial), 
the current setting is kept in a field of the control record. The 
control record also contains the minimum and maximum values the setting 
can assume. 


The control record also includes a 32-bit reference value field, which 
is reserved for use by your application program. You specify an 
initial reference value when you create a new control, and can then 
access or change the reference value whenever you wish. The Control 
Manager completely ignores the contents of this field; your program can 
use it in any way you like. 

A control record is a dynamic data structure and is referred to by a 
handle, as discussed further under "Control Handles below. You can 
access and store into most of its fields with Control Manager routines, 
so normally you don't have to know the exact field names. However, if 
you want more information about the exact structure of a control record 
— for instance, if you're defining your own control types — you'll find 
it below under "The ControlRecord Data Type • 


Control Handles _ 

Storage space for control records is allocated from your program s 
relocatable heap zone. To allow the Operating System's memory 
management routines to move them as needed without creating dangling 
pointers, they're normally referred to by double indirection, through a 
control handle (a pointer to a master pointer): 

TYPE ControlPtr = "ControlRecord; 

ControlHandle = "ControlPtr; 


(eye) 

To maintain the integrity of the storage allocation 
system, always create and dispose of control records with 
the Control Manager routines provided for this purpose, 
rather than the Pascal standard procedures NEW and 
DISPOSE. The Control Manager functions for creating a 
new control return a handle to a newly allocated control 
record; thereafter, your program should normally refer to 
the control by this handle. Most of the Control Manager 
routines expect a control handle as their first 
parameter. 
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For purposes of efficiency (for example, inside a loop that your 
program executes many times), you may sometimes want to refer to a 
control by single indirection, using a pointer instead of a handle. 

For example, 

VAR aPointer: ControlPtr; 

allandle: ControlHandle; 

. . . ; 

BEGIN 

• • • J 

aHandle := NewControl( . . . ); 
aPointer := aHandle^; 

• • • 

END. 

But BE CAREFUL! Any operation that allocates storage from the heap may 
trigger a heap compaction, which would move (relocate) the underlying 
control record and leave the pointer dangling. Not only is this type 
of error usually disastrous, it's also very difficult to diagnose and 
correct. So you can safely use single indirection to refer to a 
control record only if you're sure you're not doing anything that may 
cause fresh storage to be allocated from the heap. 

Handles don't suffer from this problem: the handle points to a master 
pointer, which in turn points to the control record. When the record 
is moved during a heap compaction, the master pointer is updated to 
point to the record at its new location; the master pointer itself is 
never moved. Thus you can rely on the handle not to dangle, even after 
a compaction. 


The ControlRecord Data Type 

This section contains detailed information on the structure of control 
records, for those who need it (for example, to define their own 
control types). The type ControlRecord is defined as follows: 

TYPE ControlRecord - RECORD 


nextControl: 

ControlHandle; 

contrlOwner : 

WindowPtr ; 

contrlRect : 

Rect; 

contrlVis: 

BOOLEAN; 

contrlHilite: 

Byte; 

contrlValue: 

INTEGER; 

contrlMin: 

INTEGER; 

contrlMax: 

INTEGER; 

contrlProc: 

Handle; 

contrlData: 

Handle; 

contrlAction: 

ProcPtr; 

contrlRfCon: 

Longlnt; 

contrLTitle: 

Str255 


END; 
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NextControl is a handle to the next control associated with this 
control's window. All the controls belonging to a given window are 
kept in a linked list, beginning in the controlList field of the window 
record and chained together through the nextControl fields of the 
individual control records. The end of the list is marked by a NIL 
value; as new controls are created, they are added to the beginning of 
the list. 

ContrlOwner is a pointer to the window to which this control belongs. 

Notice that the contrlOwner field contains a pointer to the window, not 
a handle. This is because a window record is actually a grafPort with 
some extra fields added. Since the QuickDraw graphics package refers 
to graf Ports by pointers rather than handles, the Toolbox follows the 
same convention. 

ContrlRect is the rectangle that completely encloses the control, 

expressed in the local coordinates, of the control's window. You define 

this rectangle when you create the control, and can change its size or 

position at any time. When drawn, the control may be either scaled or ^ 

clipped to this rectangle, depending on its control type; the choice is 

up to the control definition function. 

When contrlVis is TRUE, the control is currently visible. 

ContrlHilite is an integer between 0 and 255 that specifies whether and 
how the control is to be highlighted on the screen. A value of 0 means 
no highlighting; 255 means that the control is inactive and should be 
highlighted accordingly. Any other value is interpreted as a part code 
designating the part of the control that is highlighted. 

ContrlValue is the control's current setting. For two-state controls 
such as check boxes and radio buttons, a value of 0 means the control 
is off and 1 means it's on. For dials, the fields contrlMin and 
contrlMax define the range of possible settings; contrlValue may take 
on any value within that range. Other (custom) control types can use 
these three fields as they see fit. 

ContrlProc is a handle to the control definition function for this type 
of control. When you create a new control, you identify its type with ^ 

a control definition ID; this is converted into a handle to the control 
definition function and stored into the contrlProc field. Thereafter, 
the Control Manager uses this handle to access the definition function; 
your program should never need to refer to this field directly. 

(hand) 

The high— order byte of the contrlProc field contains some 
additional information that the Control Manager gets from 
the control definition ID; for details, see the section 
"Defining Your Own Controls". 

( hand ) . , . 

If you write your own control definition function and 

will not be sharing it with other programs, you can 
include it as part of your application program (instead 
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of putting it in a resource file) and just store a handle 
to it in the contrlProc field. See "Defining Your Own 
Controls” for further information. 

ContrlAction is a pointer to the controls default action procedure, 
used by the Control Manager function TrackControl to respond to the 
user's dragging the mouse inside the control. For more information on 
action procedures, see the description of the TrackControl function, 
below. 

ContrlRfCon is the controls reference value. This field is provided 
strictly for the convenience of the application program, and you can 
use it for any purpose you wish. 

ContrlData is a utility field reserved for use by the control 
definition function, typically to hold additional information specific 
to a particular control type. For example, the standard definition 
function for scroll bars uses this field for a handle to the region 
containing the scroll bar's thumb. If no more than four bytes of 
additional information are needed, the definition function can store 
the information directly in the contrlData field instead of using a 
handle. 

ContrlTitle is the control's title, a variable-length string with a 
maximum length of 255 characters. The title is optional; some control 
types (such as scroll bars) don't display one. Notice that the title 
is given as a plain ASCII string, without CoreEdit-style formatting; 
the control definition function determines the type font, type size, 
and character style to use in displaying the title. 


USING THE CONTROL MANAGER . 

This section discusses how the Control Manager routines fit into the 
general flow of your program and gives you an idea of which routines 
you'll need to use. The routines themselves are described in detail in 
the next section. 

To use the Control Manager, you must have previously called the | 

QuickDraw routine InitGraf to initialize QuickDraw. You should also 
have called the Resource Manager routine OpenResFile to open any 
resource files that you'll be using (other than the system resource 
file, which is opened automatically). 

Where appropriate in your program, use NewControl or GetNewControl to 
create any controls you need. NewControl takes descriptive information 
about the new control from its parameters; GetNewControl gets the 
information from a control template in a resource file. When you no 
longer need a control, call DisposeControl to remove it from its 
window's control list and free the memory it occupies. To dispose of 
all of a given window's controls at once, use KillControls . 
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(hand) 

The Window Manager routines DisposeWindow and CloseWindow 
automatically dispose of all the controls associated with 
the given window. 

When the Event Manager reports that an update event has occurred for a 
window, your program should call DrawControls to redraw the window s 
controls as part of the process of updating the window. 

After receiving a mouse-down event from GetNextEvent , 

1. First call FindWindow to determine in which part of which window 
the mouse button was pressed. 

2. If it was in the content region of the active window, next call 
FindControl for that window to find out whether it was in an 
active control, and if so, in which part of which control. 

3. Finally, take whatever action is appropriate when the user presses 
the mouse button in that part of the control, using routines such 
as TrackControl (to perform some action repeatedly for as long as 
the mouse button is down, or to allow the user to drag the 
controls moving indicator with the mouse), DragControl (to allow 
the user to drag the entire control with the mouse) , and 
HiliteControl (to change the way the control is highlighted on the 

screen). 

Wherever needed in your program, you can call HideControl to make a 
control invisible or ShowControl to make it visible* Similarly , 
MoveControl, which simply changes a control s location without pulling 
around an outline of it, can be called at any time, as can SizeControl, 
which changes its size — though you shouldn t surprise the user by 
taking these actions unexpectedly. 

Whenever necessary, you can read the current setting of a control with 
GetCtlValue, or other attributes with GetCTitle, GetCtlMin, GetCtlMax, 
GetCRefCon, or GetCtlAction; you can change them with SetCtlValue, 
SetCTitle, SetCtlMin, SetCtlMax, SetCRefCon, or SetCtlAction. 
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CONTROL MANAGER ROUTINES 


This section describes the routines (procedures and functions) that 
make up the Control Manager. 

Initialization and Allocation 


FUNCTION NewControl (theWindow: WindowPtr; boundsRect: Rect; title: 

Str255; visible: BOOLEAN; value: INTEGER; rain: INTEGER; 
max: INTEGER; procID: INTEGER; ref Con: Longlnt) : 
ControlHandle; 

NewControl creates a new control record, links it to the beginning of - 
theWindow's control list, and returns a handle to the new record. It 
initializes the new record's fields to the values passed as parameters, 
setting the contrlHilite field to 0 (no highlighting) and contrlAction 
to NIL (no default action procedure; see TrackControl under "Mouse 
Location", below). It also calls the control definition function to 
perform any type-specif ic initialization that may be needed, such as 
setting the contrlData field. 

TheWindow is the window the new control will belong to. All 
coordinates pertaining to the control will be interpreted in this 
window's local coordinate system. 

BoundsRect, a rectangle expressed in theWindow's local coordinates, 
determines the control's size and location. 

Title is the control's title. The string you supply as the value of 
this parameter will be stored in the control's contrlTitle field, but 
some types of control will never use it. In this case, you can just 
pass an empty string as the title. 

If the visible parameter is TRUE, NewControl calls the control 
definition function to draw the control. 

The min and max parameters define the control's range of possible 
settings; the value parameter gives the initial setting, and must fall 
within the specified range. For controls that don't retain a setting, 
such as simple buttons, the values you supply for these parameters will 
be stored into the corresponding fields of the control record, but will 
never be used. So it doesn't matter what values you give— 0 for all 
three parameters will do. For controls that just retain an on-or-off 
setting, such as check boxes or radio buttons, min should be 0 (meaning 
the control is off) and max should be 1 (meaning it's on). For dials, 
you can specify whatever numerical values are appropriate for min, max, 
and value . 

ProcID is the control definition ID, which leads to the control 
definition function for this type of control. The control definition 
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IDs for the standard control types are listed above under "Contro 
Resources'’. Control definition IDs for custom control types are 
discussed under "Defining Your Own Controls", below. 



Ref Con is the control's reference value, set and used only by your 
application program. 


FUNCTION Ge l NewCont rol (controlID: INTEGER; theWindow: Window? tr) : 
ControlHandle; 

GetNewControl creates a new control record from a control template 
stored in a resource file, links it to the beginning of theWindow ' 3 
control list, and returns a handle to the new record. ControlID is id •: 
resource ID of the template in the resource file. GetNewCont ro L works 
exactly the same as NewControl (see above), except that it gets the 
.nitial values for the new control's fields from the specified contro- 
template instead of accepting them as parameters. 


PROCEDURE DisposeControl (theControl: ControlHandle) ; 

. isposeControl erases theControl from the screen, deletes it from its 
window's control list, and disposes of its storage. It returns to Cue 
■da p all data structures associated with the control. It also calls 
the control definition function to do any type-specific housekeeping 
• hat. may be needed, such as disposing of a data structure whose handle 
is kept In the contrlData field. 

I OWE DU RE K i l ICo n t ro Is ( t heWi ndow : WindowP tr ) ; 

; li 11 Contro Is disposes of all controls associated with theWindow by 
.ailing DisposeControl (see above) for each. 


Coot rol Display 

he* routines in this section affect the appearance of a control bu i.>, 
ts size or Location. 


1 doC EDU RE SelCTi tie (theControl: ControlHandle; theTitle: Str2io), 

;ct.CUitie sets theControl " s title to theTitle. The control def Initio-, 
I unction determines the type font, type size, and character style to 
?se in displaying the title; it may use the system font, that of .he 
..uitrol's window, or any other font it chooses, or it may choose t 

display the title at all. 

- id lid ) 

Buttons, check boxes, and radio buttons all display tneir 
titles in the standard system font; scroll bars don t 
display a title. 
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PROCEDURE GetCTitle (theControls ControlHandle; VAR theTitle: Str255); 

GetCTitle returns theControl's current title string as the value of the 
parameter theTitle, regardless of whether the definition function for 
this control type actually uses the title. 


PROCEDURE HideControl (theControl: ControlHandle) ; 

HideControl makes theControl invisible. It sets the contrlVis field to 
FALSE and fills the region the control occupies within its window with 
the window's background pattern. It also adds the control's enclosing 
rectangle to the window's update region, so that anything else that was 
previously obscured by the control will reappear on the screen. If the 
control is already invisible, HideControl has no effect. 


PROCEDURE ShowControl (theControl: ControlHandle); 

ShowControl makes theControl visible. It sets the contrlVis field to 
TRUE and calls th.e control definition function to do the actual 
drawing. The control is drawn in its proper plane on the screen, and 
may be completely or partially obscured by overlapping windows or other 
objects. If the control is already visible, ShowControl has no effect. 


PROCEDURE DrawControls (theWindow: WindowPtr); 

DrawControls draws all controls currently visible, in theWindow. The 
controls are drawn in reverse order of creation; thus in case of 
overlap the earliest-created controls appear fr.ontmost in the window. 

(hand) 

Window Manager routines such as SelectWindow, ShowWindow, 
and BringToFront do not automatically call DrawControls 
to display the window's controls. They just add the 
appropriate regions to the window's update region, 
generating an update event. Your program should always 
call DrawControls explicitly on receiving an update event 
for a window. 


PROCEDURE HiliteControl (theControl: ControlHandle; hiliteState: 
INTEGER) ; 

HiliteControl changes the way theControl is highlighted on the screen. 
HiliteState is an integer between 0 and 255. A value of 0 means no 
highlighting; 255 means that the control is to be made inactive and 
highlighted accordingly. Any other value is* interpreted as a part code 
designating the part of the control to be highlighted. HiliteControl 
sets the contrlHilite field to the designated value, then calls the 
control definition function to redraw the control with its new 
highlighting. 
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Mouse Location 


FUNCTION TestControl (theControl: ControlHandle; thePoint: Point) : 

. INTEGER; 

TestControl tests which part of theControl contains thePoint and 
returns the corresponding part code, or 0 if the point is outside the 
control. If the control is invisible or inactive, no test is performed 
and TestControl returns a result of 0. 


FUNCTION FindControl (thePoint: Point; theWindow: WindowPtr; VAR 
theControl: ControlHandle) : INTEGER; 

FindControl finds which of theWindow's active controls, if any, 
contains thePoint. It returns a handle to the control as the value of 
the parameter theControl; the function result is a part code 
identifying the part of the control that contains the given point. The 
point must be expressed in the window's local coordinate system. 

When a mouse down event occurs, you should normally call the Window 
Manager function FindWindow to find out in which window, if any.^the 
mouse button was pressed. Next, if it was pressed in the window s 
content region, call FindControl to see whether it was in any of the 
window's controls. If so, you can then do whatever is appropriate for 
a mouse down event in that control (for example, call TrackControl or 
DragControl) * 

(eye) 

Notice that FindControl expects the mouse point in local 
(window) coordinates, whereas FindWindow expects it in 
global coordinates. Always be sure to convert the point 
to local coordinates with the QuickDraw procedure 
GlobalToLocal before calling FindControl. 

FindControl calls TestControl (see above) for each of the window's 
active controls to see whether it contains the given point. In the 
event of overlap, FindControl returns the frontmost control containing 
the point. If the point doesn't lie within any active control, it 
returns NIL for the control and 0 for the part code. (It also returns 
these values if the window is invisible or doesn t contain the given^ 
point. In these cases, however, FindWindow wouldn t have returned this 
window in the first place, so the situation should never arise.) 






FUNCTION TrackControl (theControl: ControlHandle; startPt: Point; 
actionProc: ProcPtr) : INTEGER; 

TrackControl is the routine that does the actual work of a control. 

When called with the mouse button down, it keeps control until the 
button is released, following the movements of the mouse and responding 
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in whatever way is appropriate, depending on the type of control and 
the part of the control in which the button was pressed. 

The actionProc parameter is a pointer to an action procedure ; it 
defines some action to be performed repeatedly for as long as the user 
holds down the mouse button. For example, when the mouse button is 
pressed in the up or down arrow of a scroll bar, the action procedure 
should scroll the contents of the window one line in the indicated 
direction. This will cause the window's contents to scroll 
continuously, one line at a time, for as long as the button is held 
down. 

If the actionProc parameter i s NIL, TrackControl simply retains control 
until the mouse button is released, performing no action while the 
button is down beyond highlighting the control or dragging its 
indicator. If actionProc is POINTER(-l), TrackControl uses the 
control's default action procedure (if any), stored in the contrlAction 
field of the control record. 

(hand) 

Actually, the default action procedure is used whenever 

the value of the actionProc parameter is odd. This 

causes no conflict, since genuine procedure pointers are 

always even (aligned on a word boundary). 

The parameter startPt is assumed to be the screen location where the 
mouse button was pressed, expressed in local window' coordinates. 
TrackControl finds which part of the control contains the given point, 
then focuses its attention only on that part. Its behavior depends on 
whether the part is the indicator of a dial (that is, whether it has a 
part code > 127). 

If the part is an indicator, TrackControl drags a flickering outline of 
the indicator to follow the mouse until the button is released. (The 
process is similar to that described below under DragControl, except 
that only the indicator is dragged and not the whole control. The 
control definition function calculates the limiting rectangle, slop 
rectangle, and axis parameter for this operation.) In this case, the 
action procedure passed to TrackControl, if any, should take no 
parameters. For example, if the name of the action procedure is 
Action, it should be declared simply as 

PROCEDURE Action; 

When the user releases the mouse button, TrackControl calls the control 
definition function to reposition the control s indicator, passing the 
vertical and horizontal offset. through which the mouse was dragged. 

It's up to the definition function to adjust the control's setting, 
redraw the control, or take whatever other action is appropriate. For 
example, the standard definition function for scroll bars redraws the 
scroll bar's thumb, calculates its new relative position within the 
shaft, and scrolls the window to the corresponding relative position in 
the document. 
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If the control is not a dial, or if tne mouse button was initially 
pressed in a part of a dial other than the indicator, the action 
procedure (if any) should be of the form 

PROCEDURE Action (theControl: ControlHandle; partCodr-: INTEGER) 

la this case, TrackControl repeatedly reads the position of the. mouse 
for as long as the button remains down, testing whether it s still in 
the original part of the control. If so, TrackControl highlights the 
part and passes its part code to the action procedure, along with a 
handle to the control itself- If the mouse is outside the original 
control part* — that is, if the user has moved out of the part while 
still holding down the button— “TrackControl unhighlights the part and 
passes a part code of 0 to the action procedure. In either case, 
TrackControl reads the mouse's position again and repeats the process 

until. the mouse button is released* 

when the user finally releases the button, TrackControl unhj-ghl igh t 
the control * If the button is released inside the same part of the 
control in which it was originally pressed, TrackControl returns the 
part code for that part; if not, it returns 0* You can use this 
information, for example, to allow the user to back out of an 
operation by moving the mouse out of the control, before releasing the 
button. 


Control Movement and Sizing 


PROCEDURE Mo veCo ti.tr ol (theControl: ControlHandle ; h, v: 


INTEGER) ; 


MoveControl moves theControl to a new location within its window- ^ The 
top left corner of the control's enclosing rectangle is moved to the 
new horizontal and vertical coordinates h and v; the bottom right 
corner is adjusted accordingly, to keep the size of the rect^cgle the 
same as before. If the control is currently visible, it is hidden and 
then redrawn at its new location. 


PROCEDURE DragControl (theControl: ControlHandle; startPt: Point; 
limitRect, slopRect: Rect; axis: INTECiER) ; 

When ealLed with the mouse button down, DragControl allows the user to 
drag a flickering outline of theControl around the screen with the 
mouse. It follows the movements of the mouse for as long as the button 
is held down, then calls MoveControl (see above) to move the control to 
the position where the button was released* 

thand) ... ,, 

Before beginning to follow the mouse, Draguoutrol oa*is 

the control definition function to allow it to do its owu 
’"custom dragging" if it chooses. If the definition 
function doesn^t choose to do any custom dragging, 
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DragControl uses the default method of dragging described 
here. 


The startPt parameter is assumed to be the point where the mouse button 
was originally pressed, expressed in the local coordinates of the 
control's window. The limitRect rectangle limits the travel of the 
control, and should normally coincide with or be contained within the 
window's content region. DragControl will never move the top left 
corner of the control outside this rectangle, regardless of where the 
user drags the mouse. The second rectangle, slopRect , allows the user 
some "slop** in moving the mouse; it should completely enclose the 
limiting rectangle. DragControl's behavior while tracking depends on 
the position of the mouse with respect to these two rectangles: 

- When the mouse is inside limitRect, the control's flickering 
outline follows it normally; if the button is released, the 
control will be moved to the mouse position. 

- When the mouse is outside limitRect but inside slopRect, the 
control's outline "pins" at the edge of limitRect; if the button 
is released, the control will be moved to this "pinned” location. 


When the mouse is outside slopRect, the control's outline 
disappears from the screen, but DragControl continues to follow 
the mouse; if it moves back into slopRect, the outline reappears. 
If the button is released outside slopRect, the control will not 
be moved from its original position. 


The axis parameter allows you to constrain the control's motion to only 
one axis: 


Axis Parameter 


0 

1 

2 


Meaning 
No constraint 
Horizontal motion only 
Vertical motion only 


If an axis constraint is in effect, the control will follow the mouse's 
movements along the specified axis only, ignoring motion along the 
other axis. With or without an axis constraint, the mouse must still 
be inside the slop rectangle for the control to move at all. 


PROCEDURE SizeControl (theControl: ControlHandle; w, h: INTEGER); 

SizeControl changes the size of theControl's enclosing rectangle. The 
bottom right corner of the rectangle is adjusted to set the rectangle's 
width and height to w and h; the position of the top left corner is not 
changed. If the control is currently visible, it is hidden and then 
redrawn in its new size. The actual drawing is done by the control 
definition function, which may either scale or clip the control to its 
new enclosing rectangle. 
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Setting and Range of a Control 


PROCEDURE SetCtlValue (theControl: ControlHandle; theValue: INTEGER); 

SetCtlValue sets theControl's current setting (contrlValue) to theValue 
and redraws the control to reflect the new setting. If the specified 
value is out of range, it is forced to the nearest endpoint of the 
current range. That is, if theValue contrlMin, contrlValue is set to 
contrlMin; if theValue > contrlMax, contrlValue is set to contrlMax. 


FUNCTION GetCtlValue (theControl: ControlHandle) : INTEGER; 
GetCtlValue returns theControl's current setting (contrlValue). 


PROCEDURE SetCtlMin (theControl: ControlHandle; rainValue: INTEGER); 

SetCtlMin sets theControl's minimum setting (contrlMin) to minValue and 
redraws the control to reflect the new range. If minValue is greater 
than the control's current setting (contrlValue), the setting is 
changed to the new minimum value. 


FUNCTION GetCtlMin (theControl: ControlHandle) : INTEGER; 
GetCtlMin returns theControl's current minimum value (contrlMin). 


PROCEDURE SetCtlMax (theControl: ControlHandle; raaxValue: INTEGER); 

SetCtlMax sets theControl's maximum setting (contrlMax) to raaxValue and 
redraws the control to reflect the new range. If maxValue is less than 
the control's current setting (contrlValue), the setting is changed to 
the new maximum value. 


FUNCTION GetCtlMax (theControl: ControlHandle) : INTEGER; 
GetCtlMax returns theControl's current maximum value (contrlMax). 

Miscellaneous Utilities 


PROCEDURE SetCRefCon (theControl: ControlHandle; refVal: Longlnt); 

SetCRefCon sets theControl's reference value to refVal. The reference 
value is reserved for use by your program, which can use it in any way 
you wish; it is ignored by the Control Manager itself. 
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FUNCTION GetCRefCon (theControi: ControlHandle) : Longlnt; 
GetCRefCon returns theControl's current reference value. 


PROCEDURE SetCtlAction (theControi: ControlHandle; actionProc: 
ProcPtr); 

SetCtlAction sets theControl's default action procedure to actionProc. 
TrackControl uses this procedure to respond to the user's dragging the 
mouse inside the control; for more information, see TrackControl under 
"Mouse Location", above. 


FUNCTION GetCtlAction (theControi: ControlHandle) : ProcPtr; 

GetCtlAction returns a pointer to theControl's default action 
procedure. TrackControl uses this procedure to respond to the user's 
dragging the mouse inside the control; for more information, see 
TrackControl under "Mouse Location", above. 


FORMAT OF A CONTROL TEMPLATE 


As described above, you can use the GetNewControl function to create a 
new control from a template stored in a resource file. Such a template 
contains the same information that the NewControl function gets from 
eight of its parameters. The resource type for a control template is 
'CTRL', and the resource data has the following format: 


Number of bytes 
8 bytes 
2 bytes 
2 bytes 
2 bytes 
2 bytes 
4 bytes 
4 bytes 
n bytes 


Contents 

Same as boundsRect parameter to NewControl 
Same as value parameter to NewControl 
Same as visible parameter to NewControl 
Same as max parameter to NewControl 
Same as min parameter to NewControl 
Same as procID parameter to NewControl 
Same as refCon parameter to NewControl 
Same as title parameter to NewControl 
(1-byte length in bytes, followed by the 
characters of the title) 


DEFINING YOUR OWN CONTROLS 


In addition to the standard, built-in control types (buttons, check 
boxes, radio buttons, and scroll bars), the Control Manager allows you 
to define "custom" control types of your own. Maybe you need a 
three-way selector switch, a disk— space indicator that looks like a 
thermometer, or a thruster control for a spacecraft simulator whatever 
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your particular application calls for. This section contains the 
information you need to define your own control types to meet your 
program's special needs. 


(hand) 


For the convenience of your program's user, remember to 
conform to the Macintosh User Interface Guidelines for 
controls as much as possible. 


Every control type is defined by a control definition function, which 
is normally stored in a resource file; its resource type is CDE - o 

define a control type of your own, you write a control definition 
function and (usually) store it in a resource file, with a resource 
type of 'CDEF' and a resource ID of your own choosing. resource 

data is simply the compiled or assamblad coda of the control deflation 
function, which may be written in Pascal or assembly language, the only 
requirement is that its entry point must be at the beginning. 

^ eye ^ Resource IDs 0 through 8 are reserved for predefined 

control definition functions in the system resource file. 

Unless you want to override one of the built-in 
functions, the resource ID you choose for your own 
control definition function should be greater than 8. 

Whenever you create a new control, you specify its type by giving a 
control definition ID. This is a 16-bit integer that contains the 
resource ID of the control definition function in its upper 12 bit. , 
aSng wUb a variation code in the lower four bits. Thus, for a given 
resource ID and variation code, the control definition ID is. 

16 * resource ID + variation code 

The variation code allows a single control definition function to 
implement several related control types as "variations on a theme . 

For example, buttons, check boxes, and radio buttons all use the 
standard definition function whose resource ID is 0 , but they nave 
variation codes of 0, 1, and 2, respectively. 

The Control Manager calls the Resource Manager to find the resource of 
type 'CDEF' with the given resource ID. The Resource Manager searches 
first in any application resource files, in the reverse order they were 
opened, and last in the system resource file. When it finds the 
requested resource, it reads the resource s data (tne code of the 
control definition function) into memory and returns a handle to • 

The Control Manager stores this handle in the contrlProc ie 1 c 

new control record, along with the variation code in the high order 
byte of the field. Later, when it needs to perform a type-dependen. 
action on the control, it uses the handle to find the co^ro 
definition function and passes it the variation code as a paramete 

Figure 5 illustrates this process. 
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Coi\Uol deiutiuofv ID supplieii -if hen control v? croo.vo<i', 


resourcelD f var [ 
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12 bits 4 bits 


1 r£ 30 ]ji t £& ID of control 
definition function 
ond v oi lotion code) 


Resource Meiio^er cell rne.de by Control Manager: 

deffiandle = OetJlesource f'CDEF', resourceJD); 


Field in control record; 
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j j vet | defHen.dle 

s , 

pd23ed to control rlefinition function 


Figure 5. Control Definition Handling 


(hand) ... . 

If you won" t be sharing your control definition function 

with other application programs, you may find it more 
convenient to include it with the code of your program 
instead of placing it in a resource file. If you do 
this, you have to supply a dummy control .definition ID 
when you create a new control of this type, pointing to a 
definition function that IS stored in a resource file 
for example, the definition ID of one of the standard 
control types — and specify that the control initially be 
made invisible. Once the control is created, you can 
replace the contents of the contrlRroc field with a 
handle to the actual control definition function (along 
with a variation code, if needed, in the high - order byte 
of the field). You can then call ShowControl, if 
necessary, to make the control visible within its window. 


Format of a Control Definition Function 


You can give your control definition function any name you like. 

Here's how you would declare one named MyControl : 

FUNCTION MyControl (varCode: INTEGER; theControl: ControlHandle; 

theMessage: ControlMessage; parara: Longlnt) : Longlnt 

VarCode is the variation code, as described above. 
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TheControl is a handle to the control that the operation will affect. 

TheMessage is a control message identifying the desired operation: 

TYPE ControlMessage = (drawCntl, testCntl, calcCRgns, initCntl, 

/Hcnr.ntl. nosCntl. thumbCntl, dragCntl), 


Message 

drawCntl 

testCntl 

calcCRgns 

initCntl 

dispCntl 

posCntl 

thumbCntl 

dragCntl 


Operation 

Draw the control in its window 

Test in what part of the control (if any) the 

mouse button was pressed 

Calculate the control's region (or that of 
its indicator) within its window 
Do any special control initialization 
Take any special actions when the control is 

disposed of , 

Reposition the control's indicator and update 

its value accordingly 

Calculate the parameters for dragging the 

control's indicator with the mouse 

Drag the control (or its indicator) with the mouse 


As described below in the discussions of the routines that 
these operations, the value passed for param, the last parameter of t 
control definition function, depends on the operation. Where it is n 
mentioned below, this parameter is Ignored. Similarly, the control 
definition function is expected to return a function result only whe 
indicated; in other cases, the function should return 0. 


(hand) 


"Routine" here does not necessarily mean a procedure or 
function. While it's a good idea to set these up as 
subprograms inside the window definition function, you 
are not required to do so. 




The Draw Routine 


The message drawCntl asks the control definition function to draw all 
or part of a control within its window. The value of param is a part 
code specifying which part of the control to draw or 0 for e ntire 

control. If the control is invisible (that is, if its contrl 
is FALSE) there's nothing to do; if it's visible, the definition 
function^ shoult/draw 1C (!r the requested pert) tehl„ 3 Into account 
the current values of its contrlHilite and contrlValue fields. 




(eye) 


The Control Manager procedures SetCtlValue, SetCtlMin, 
and SetCtlMax all send the message drawCntl with a part 
code parameter of 128, asking the control definition 
function to redraw a control's moving indicator. or 
control types using other part codes to represent 
indicators, the definition function must detect a param 
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value of 128 as a special case and redraw all indicators, 
regardless of part code. 


The Test Routine 


The message testCntl asks in which part of a control, if any, a given 
point lies. The point is passed as the value of param, expressed as a 
four-byte record of type Point (not a pointer or a handle) in the local 
coordinates of the control's window. The control definition function 
should return the part code for the part of the control that contains 
the point; it should return 0 if the point is outside the control's 
region or if the control is inactive (contrlHilite = 255). 


The Routine to Calculate Regions 


The control definition function should respond to the message calcCRgns 
by calculating the region a control occupies within its window. Param 
is a QuickDraw region handle; the definition function should update 
this region to the shape, size, and position of the control, expressed 
in the local coordinate system of its window. 

If the high-order bit of param is set, ,th£ region requested is that of 
the control's indicator, rather than that of the control as a whole. 

The definition function should clear the high BYTE (not just the high 
bit) of the region handle before attempting to update the region. 

(hand) 

Notice that the control and its indicator aren't limited 
to rectangular boxes, but may occupy regions of any 
shape, in the full generality permitted by QuickDraw. 


The Initialize Routine 


When it creates a new control, the Control Manager sends the message 
initCntl to the control definition function. This gives the definition 
function a chance to perform any type-specific initialization it may 
require. For example, the standard definition function for scroll bars 
allocates space for a region to hold the scroll bar's thumb location 
and stores the region handle in the contrlData field of the new control 
record. The initialization routine for buttons, check boxes, and radio 
buttons does nothing. 


The Dispose Routine 


The Control Manager's DisposeControl procedure sends the message 
dispCntl to the control definition function, telling it to carry out 
any special "housekeeping" associated with disposing of a control. For 
example, the standard definition function for scroll bars deallocates 
the space occupied by the thumb region, whose handle is kept in the 
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controls contrlData field* The dispose routine for buttons, check 
boxes, and radio buttons does nothing. 


The Position Routine 


The message posCntl tells the control definition function to reposition 
a controls moving indicator and update the control s setting 
accordingly * The value of param is a point giving the vertical and 
horizontal offset, in screen pixels, by which the indicator is to be 
moved relative to its current position. (Typically, this is the offset 
between the points where the user pressed and released the mouse button 
while dragging the indicator.) The vertical offset is given in the 
high-order word of the Longlnt and the horizontal offset in the 
low-order word. The definition function should calculate the control's 
new setting based on the given offset, update the contrlValue field, 
and redraw the control within its window to reflect the new setting. 


(hand) 


If you use the Control Manager procedure SetCtlValue to 
update the contrlValue field, the control will be redrawn 
automatically. 


The Thumb Routine 

The control definition function should respond to the message thumbCntl 
by calculating the limiting rectangle, slop rectangle, and axis 
constraint for dragging a control's indicator with the mouse (see the 
descriptions of DragControl and TrackControl, above). Param is a 
pointer to a data structure of type 

RECORD 

limitRect, slopRect: Rect; 
axis: INTEGER 
END; 

On entry, parain~ . limi tRec t * topLe t L contains the point wheie the mouse 
button was first pressed. The definition function should store the 
appropriate values into the fields of the record pointed to by param. 


The Drag Routixie .. 

The message dragCntl asks the control definition function to drag a 
control or its indicator around on the screen to follow the mouse until 
the user releases the mouse button. Param is a Boolean value 
specifying whether to drag the indicator or the whole control. TRUE 
means just drag the indicator. 

The control definition function need not implement any form of custom 
dragging"; if it returns a result of 0, the Control Manager will use 
its own default method of dragging (see the description of DragControl 
above). Conversely, if the control definition function chooses to do 
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its own custom dragging, it. should signal the Control Manager not to 
use the default method by returning a nonzero result. 

If the whole control is being dragged, the definition function should 
call MoveControl to reposition the control to its new location after 
the user releases the mouse button. If just the indicator is being 
dragged, the definition function should execute its own position 
routine (see above) to update the controls setting and redraw it in 
its window. 


NOTES FOR ASSEMBLY-LANGUAGE PROGRAMMERS 


Information about how to use the User Interface Toolbox from assembly 
language is given elsewhere. *** For now, see the QuickDraw manual. 
*** This section contains special notes of interest to progrmmers who 
will be using the Control Manager from assembly language. 

The primary aid to assembly-language programmers is a file named 
TOOLEQU.TEXT . If you name this file in an .INCLUDE statement when you 
assemble your program, all the Control Manager constants, offsets to 
locations of global variables, and offsets into the fields of 
structured types will be available in symbolic form. 
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SUMMARY OF THE CONTROL MANAGER 


CONST PushButProc = 0; 
CheckBoxProc = 1; 
RadioButProc - 2; 
ScrollBarProc. = 16; 

inButton = 10; 
inCheckBox = 11; 

inUpButton = 20; 
inDownButton = 21; 
inPageUp = 22; 
inPageDown = 23; 
inThumb = 129; 


{simple button} 

{check box} 

{radio button} 

{scroll bar} 

{simple button} 

{check box or radio button} 

{up arrow of a scroll bar} 

{down arrow of a scroll bar} 

{"page up M region of a scroll bar} 
{"page down" region of a scroll bar} 
{thumb of a scroll bar} 


TYPE ControlHandle = ~ControlPtr ; 

ControlPtr = "ControlRecord; 

ControlRecord = RECORD 


nextControl: 

ControlHandle; 

contrlOwner : 

WindowPtr; 

contrlRect : 

Rect; 

contrlVis: 

BOOLEAN; 

contrlHilite: 

Byte; 

contrlValue: 

INTEGER; 

contrlMin: 

INTEGER; 

contrlMax: 

INTEGER; 

contrlProc: 

Handle; 

contrlData: 

Handle; 

contrlAction: 

ProcPtr; 

contrlRfCon: 

Longlnt ; 

contrlTitle : 

Str255 


END; 

ControlMessage — (drawCntl, testCntl, calcCRgns, initCntl, 
dispCntl, posCntl, thumbCntl, dragCntl); 


Initialization and Allocation 


FUNCTION NewControl (theWindow: WindowPtr; boundsRect: Rect; 

title: 3tr255; visible: BOOLEAN; value: 
INTEGER; min: INTEGER; max: INTEGER; 
procID: INTEGER; refCon: Longlnt) : 
ControlHandle; 

FUNCTION Get NewControl (controlID: INTEGER; theWindow: WindowPtr) : 

ControlHandle ; 

PROCEDURE DisposeControl (theControl: ControlHandle) ; 

PROCEDURE KillControls (theWindow: WindowPtr); 
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Control Display 


PROCEDURE SetCTl tie 
PROCEDURE GetCTitle 

PROCEDURE HideControl 
PROCEDURE ShowControl 
PROCEDURE DrawControls 
PROCEDURE HiliteControl 


(theControl: ControlHandle; theTitle: Str255); 
(theControl: ControlHandle; VAR theTitle: 
Str255) ; 

(theControl: ControlHandle); 

(theControl: ControlHandle); 

(theWindow: WindowPtr) ; 

(theControl: ControlHandle; hiliteState: 
INTEGER) ; 


Mouse. Location 


FUNCTION TestControl (theControl: ControlHandle; thePoint: Point) : 

INTEGER; 

FUNCTION FindControl (thePoint: Point; theWindow: WindowPtr; VAR 

theControl: ControlHandle) : INTEGER; 

FUNCTION TrackControl (theControl: ControlHandle; startPt: Point; 

actionProc: ProcPtr) : INTEGER; 


Control Movement and Sizing 


PROCEDURE MoveControl (theControl: ControlHandle; h, v: INTEGER) 
PROCEDURE DragControl (theControl: ControlHandle; start?!:: Point 

liraitRect, slopRect: Rect; axis: INTEGER) 
PROCEDURE SizeControl (theControl: ControlHandle; w, h: INTEGER) 


Setting and Range of a Control 


PROCEDURE SetCtlValue 
FUNCTION GetCtlValue 
PROCEDURE SetCtlMin 
FUNCTION GetCtlMin 
PROCEDURE SetCtlMax 
FUNCTION GetCtlMax 


( theControl: 
(theControl: 
(theControl: 
(theControl: 
(theControl: 
(theControl: 


ControlHandle; theValue: INTEGER); 
ControlHandle) : INTEGER; 
ControlHandle; niinValue: INTEGER); 
ControlHandle) : INTEGER; 
ControlHandle; raaxValue: INTEGER); 
ControlHandle) : INTEGER; 


Miscellaneous Utilities 


PROCEDURE SetCRefCon (theControl: ControlHandle; refVal: Longlnt); 
FUNCTION GetCRefCon (theControl: ControlHandle) : Longlnt; 

PROCEDURE SetCtlAction (theControl: ControlHandle; actionProc: ProcPtr); 
FUNCTION GetCtlAction (theControl: ControlHandle) :... ProcPtr; 
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GLOSSARY 

action procedure: A procedure passed as a parameter to the Control 
Manager routine TrackControl , defining an action to be performed 
repeatedly for as long as the mouse button is held down. 

active control: A control that will respond to the user s actions wlt.i 
the mouse. 

button: A standard Macintosh control that causes some immediate or 

continuous action when clicked or pressed with the mouse. 

check box: A standard Macintosh control that retains and displays a 
setting, either checked (on) or unchecked (off). Clicking inside the 
check box with the mouse reverses the setting. 

control: An object in a window on the Macintosh screen with which the 

user, using the mouse, can manipulate the information in toe window ot. 
control the way it is presented. 

control definition function: A function called by the Control Manager 
when it needs to perform certain basic operations on a particular type 
of control, such as drawing the control In Its window. 

control definition ID: A number passed to control-creation routines to 
Indicate the type of control; it consists of the control definition 
function's resource ID and a variation code. 

control handle: A reference to a control record by double indirection; 
a pointer to the master pointer to the record. 

control list: A linked list of the controls associated with a given 
window, 

control message: A parameter passed to a control definition inaction 
to identify the operation desired. 

control record: The internal representa t ion of a control, where the 
Control Manager stores all the information it needs for its operations 
on that control. 

control template: A resource that con tains information from which the 
Control Manager can create a control. 

dial: A control with a moving indicator that displays a quantitative 

setting or value. Depending on the type of dial, the user may or may 
not be able to change the setting by dragging the indicator with the 
mouse. 

highlight: To dLsplay a control or part of a control in some 

distinctive visual way, such as inverting it or making its outline 
heavier. 
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inactive control; A control that will not respond to the user^s 
actions with the mouse. An inactive control. i.s highlighted in some 
special way, such as "dimming" it with light gray shading. 

indicator: The moving part of a dial that displays its current 

setting. 

invisible control: A control that is not drawn in its window. 

part code: An integer code, defined by the control definition 
function, that stands for a particular part of a control. 

radio button: A standard Macintosh control that retains and displays a 
setting, either on or off, and is part of a group with the property 
that only one button in the group can be on at a time. Clicking a 
radio button on turns off all the others in the group, like the^buttons 
on a car radio. 

reference value: In a control record, a 32-bit field which the 
application program may stor into and access for any purpose. 

variation code: A number that distinguishes closely related types of 
controls and is passed as part of a control definition ID when a 
control is created. 

visible control: A control that is drawn in^ its window (but may be 
completely overlapped by another window or other object on the screen) . 
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THE MACINTOSH CORE OF EXPLANATION 


CORE 


See Also: User Interface Guidelines 
Writer’s Style Guide 

Humor and Examples in User Learning Materials 


Modification History: First Draft Espinosa 4/18/83 

Second Draft . Espinosa 8/10/83 


ABSTRACT 

Macintosh's many new and revolutionary concepts make it very important 
to explain it in a consistent manner* The Macintosh Glossary (appearing 
in the User Interface document and the Writer's Style Guide) defines the 
terms we wish to use consistently. This document repeats those glossary 
words and, for each word, gives a sample of how to explain its concept 
or object to a new user. It's very important that all material the user 
sees conforms to (or at least does not contradict) this core of 
explanation. 


SUMMARY OF CHANGES FROM THE FIRST DRAFT: 

The humor was tweaked to conform to the guidelines of humor set forth 
in the "Humor and Examples in User Learning Materials" document. 

Words were made consistent within the document and with Pam's Style Guide 
Glossary Update. 

Cut, Paste, Copy, Undo, Edit, and Memory were added. 
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EXPLANATIONS 


Active Window 

When you have more than one window on the desk top, your Macintosh 
needs to know which one you're working on at the moment, so that your 
commands and your typing end up in the right window. That's why the 
window you're working on is in front of all others, and has its title 
highlighted: because it's the active window. Text you type and 
commands you choose all affect the document in the active window. 


Alert Message 

When your Macintosh can't carry out your wishes, or you try something 
it doesn't understand, it gives you a message telling you it’s having 
trouble. The message can come in the form of a blink of the menu bar, 
a soft beep, a louder set of tones, or an alert box with words and 
Pictures to explain the problem and what to do about it. 


Alert Box 

If a problem pops up that your Macintosh can't handle without your ~ 
help , it presents a small box explaining the problem and how to solve 
it, and perhaps giving you a couple of alternative ways to proceed. 

Application 

You can open up a document to see what's inside. But how do you work 
on it? You need tools — typographic and formatting tools for texts, 
calculation tools for spreadsheets, artist's tools for drawing and 
painting. These tools come in thge form of application programs, 
sometimes called ''applications" or "applications software". The 
Macintosh automatically gives you the proper application for a document 
when you open it. An application puts menu titles in the menu bar, and 
the menus have commands that work on your document. Two applications 
come with your Macintosh: word processing and painting. You can add 
new applications (and use new kinds of documents) at any time. 


Button 

Like most other computers, your Macintosh can do hundreds of things at 
the touch of a button. But we didn't want to put hundreds of buttons 
on the Macintosh, so we put them somewhere else — on the screen. You 
see only the buttons that make sense at the moment; the Macintosh 
doesn't confuse you with rows of inappropriate controls. And you can 
tell by looking at it what a button will do: boldly-outlined buttons 
the most common actions, and dimmed buttons don't do anything. 
To make something happen, click the button by positioning the pointer 
over it and pressing and releasing the mouse button. 
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Calculator __ _____ _ _ 

No desk top is complete without a pocket calculator. We've built one 
right into your Macintosh, so you can pull it out onto the Macintosh’- 
de 9 k top even when you’re working on a document* So we saved you iive 
bucks, and lots of batteries. 


Check Box 

When the Macintosh needs you to pick things out of a list, it puts 
little boxes next to the items in the list. You can check these boxes 
just like checking boxes on a form or ballot. To check (or uncheck) a 
check box, click it: position the pointer over it and press and 
release the mouse button. 


Choose 

You choose an item from a menu by positioning the pointer on a menu 
title, pressing and holding the mouse button, dragging down to the item 
you want, and releasing the mouse button. Choosing a menu item causes 
something to happen; first you select something to work on, then you 
choose something to do to it. 


Click ' 

You do most things on the Macintosh by positioning the pointer and 
pressing the mouse button. Usually just a click — pressing and 
releasing the mouse button™ is enough to check a check box, click a 
button, or select soimething to work on. 


Clipboard _ 

When you’re moving something from one place to another in a document 
(or from one document to another), you need a temporary place to hold 
it. The clipboard is the container that holds the things you cut out 
of a document, and from which you take things to paste in. But the 
clipboard can hold only one cutting at a time; each thing you cut 
replaces the previous contents of the clipboard. 


Close 

When you’re finished working on one document and you want to work on 
another, close the first one. Closing a document removes its window; 
all you see is the icon representing that document. Be sure to save 
any changes you have made to a document before closing it. 
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Close Box 

You close a window by bringing it to the front and choosing "Close 11 
from the File menu. But there’s a quicker way to close the frontmost 
window: click the little icon on the left side of its title bar. 
That’s the close box, and clicking it is the same as choosing ’’Close” 
from the File menu. 


Command 

Computers, like people, act on impulse. Except you’re giving your 
Macintosh the impulses. To tell it to do something, first select some 
Information to work on, then choose a command from one of its menus. 
The Macintosh rapidly performs your bidding (perhaps asking you for a 
little more information first, in a dialog box), then displays the 
results and is ready for your next idea. 


Control Panel 

Notice that the only control on the front of the Macintosh is the 
brightness knob. That’s because all the other controls are on a 
control panel on the screen. Buttons and dials on this control panel 
let you fiddle with a lot of miscellaneous adjustments, like the 
speaker volume. 


c °py : : ; , 

One of the great things about computer memory is not how much it can 
remember, or how quickly it can recall, but that it can instantly make 
a copy of anything in it. And that’s what the Copy command is for: it 
makes a copy of the current selection, saving the copy temporarily on 
the clipboard. You can then paste that copy into another place in the 
document, or even into a different document! So you can get the most 
mileage out of a great inspiration, a well-turned phrase, or a 
commonly-used drawing. 


Cut . 

Not everything you type or draw in your document will be perfect the 
first time. So cutting something out of a document (either to 
eliminate it or to move it somewhere else) should be as easy as putting 
it in. The Cut command in the Edit menu lets you cut out anything that 
you’ve selected. In some documents, cutting just blanks out the space 
occupied by the selection; in others (in text, especially) things move 
around to fill the space of what’s been cut. 
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Desk Accessories ' , 

What would you do without all the paraphernalia on your desk — clocks , 
calculators, clocks, note pads, and those little things that snow when 
you shake them? You can have such things on the Macintosh, too. If 
you're writing a letter to the loan company, you can bring the 
calculator onto the desk top to calculate how much your landlord needs. 
Or play a quick game of solitaire in the middle of a boring sales 
forecast. Or scribble a phone message on the note pad. 


Desk top 

The Macintosh is easier to use than other computers because you don't 
use it like an ordinary computer — typing numbers and acronyms and funny 
words— you use it like your desk. While most computer screens look 
like the Departing Flights at Orly Airport, the Macintosh's screen 
looks like a light gray desk top, with neat stacks of documents and 
little desk accessories off to one side. You slide papers around, open 
and close documents, and use calculators and clocks just like you would 
on your own desk. Of course, keeping your desk top neat and 
uncluttered is your own responsibility. 


Dial 

You probably bought your Macintosh to free yourselves from seas of 
numbers and computations. But in using any computer, you have to deal 
with its own numerical settings and adjustments. The Macintosh helps 
you by showing you such numbers in a more visual form. A scroll bar 
shows you your position in a document visually, rather than with 
numbers. The clock has hour, minute, and second hands (a radical 
idea!) as well as the traditional digits. And its memory indicator 
looks more like a fuel gague than "14654 BYTES FREE". On some dials 
(such as the speaker volume on the control panel), you can even change 
the setting just by dragging the dial's indicator with the pointer. 


Dialog Box __ ' 

Sometimes the Macintosh needs additional information to carry out a 
command you've given it. When this happens, the Macintosh displays a 
dialog box: a window with a description of what it wants, and some 
boxes and buttons. You fill in the bo^es, check or uncheck items, and 
click a button when you want the Macintosh to carry out the command 
using all the information you've given it. 


Disk 

Like most computers, the Macintosh's memory is limited, and its 
contents vanish when you turn off its power. Since the Macintosh can't 
keep all the information you want to use inside its memory, it lets you 
store it on a magnetic disk. The disk spins inside its plastic 
cartridge that protects it when it's not in the disk drive. It's sort 
of like a cassette tape that stores programs and documents instead of 
music. 
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Disk Drive 

Your Macintosh can't get at the information on a disk that's in your 
pocket. But put that disk in one of its disk drives and you can use 
any of the documents and programs on it. The slot on the front of the 
Macintosh gives you access to the internal disk drive. You can also 
connect an external disk drive to a socket on the back of the Macintosh 
and use another disk there. 


Document 

Just like on your own desk, there are stacks of documents on the 
Macintosh desk top. Documents include letters and correspondence, 
pictures and drawings , charts and graphs , ledger sheets , and scribbled 
calculations and estimates. On the desk top, documents are closed up 
so that you can see lots of them at a time, and each is represented by 
an icon (captioned by the document's name) that shows you what kind of 
document it is. You can see the contents of a document, and edit or 
change them, by opening it up. Since most documents are bigger than 
the desk top when opened up, you only see part of the document at a 
time: the Macintosh gives you a "window" onto the document. And when 
you need to file your documents, instead of storing them in file 
folders in file drawers, the Macintosh stores them on disks. 


Double-Click 

Experts can get the most out of their Macintoshes by using a few 
shortcuts included for them. One of these is the double-click. In 
many cases, clicking the mouse button twice (in rapid succession) will 
do something beyond what just one click does. Like in selecting 
documents on the desk: where one click selects a document, selects it 
and opens it, too. It's just like selecting it and choosing "Open" 
from the File menu, but quicker for practiced users. 


Dra g _ 

Clicking the mouse button can cause an action, select a place or an 

item, or check or uncheck a box. But sometimes you want to deal with 
more than one item or place: if you press and hold the mouse button, 
move the mouse, and release the mouse button, something happens that's 
beyond clicking. Dragging the mouse like this lets you pull down a 
menu and choose an item from it, or select whole expanses of text, or 
move something to just the place you want it. When you're moving 
something by dragging, you usually move a flickering outline of it, 
rather than the thing itself. This gives you a chance to cancel: if 
you change your mind, just drag 'way out of bounds before releasing, 
and the flickering outline vanishes and the object you were trying to 
move remains in its place* 
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Edit _ _______ __ . 

While it 1 8 time-consuming to revise a paper document, the contents of 
Macintosh’s electronic documents can easily be changed at any time. 
Adding new information, removing old stuff, replacing old with new, or 
rearranging the pictures or paragraphs is called editing. You’ll use 
the tools in the Edit menu-- cut , copy, and paste — to edit the 
information in your documents. 


Extending a Selection __ 

You have to select the information you want the Macintosh to perform 
commands on. But if you want to operate on a lot of information — say 
to change the typeface of a ten-page paper— it’s a drag (literally) to 
go all the way through the document to select the whole thing. There’s 
a shortcut: by selecting in one place, moving to another place in the 
document (scrolling if necessary), then holding down the Shift key on 
the keyboard and selecting somewhere else, you make one big selection 
that encompasses both selections and everything between them. 


Feature key 

While you’ll be using the mouse most of the time, sometimes you’ll be 
doing more typing — such as when creating a text document. And if 
you’re an expert typist, you might be faster keeping your hands on the 
keyboard, rather than having to move to the moouse to issue commands. 
So some of the commands— the ones most frequently used while 
typing— can be chosen with the feature key (to the left of the 
space bar). Holding down the feature key, type a letter associated 
with that command. The command takes effect just as if you had chosen 
it from a menu. 


Field-Motion Keys _ 

When you’re entering a lot of data into a table or list, it’s 
convenient to move the selection around while keying in the numbers. 
That’s why on the optional numeric keypad there are four keys to move 
the selection by rows and columns. 


File . 

Filing is what you do to documents to move them between the desk top 
and the disk. The File menu contains all the commands you need to file 
and retrieve your documents. 

(File is also computer jargon that refers to the little containers of 
information on a disk. You may hear that all the information on a 
disk— your stuff as well as the system’s — is stored in ’’files". And 
some computers allow (read "require") you to do some fairly complex and 
intricate things with files. Since the Macintosh allows you to think 
in terms of documents on the desk, and does all the filing for you, you 
don’t need to worry about files.) 
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Highlighting 

Just as photographers use lighting to make something stand out from its 
background, you use a special kind of highlighting to indicate the 
information you want to work on. When you select an object or some 
text, it appears distinct from others like it: objects are outlined by 
a flickering rectangle or have "knobs" by which you can manipulate 
them; text and icons are displayed in white on a black background. 


Icon 

The trouble with words is that they mean different things to different 
people. So using words on a computer screen to represent objects and 
concepts can be troublesome, especially if Modern Computer Jargon isn't 
your native tongue. The Macintosh helps you by representing some 
concepts and objects with icons, little symbolic illustrations, as well 
as words. Connectors on the back of the Macintosh are labeled with 
icons that resemble what connects to them. Documents on the desk top 
are represented by icons that indicate what kinds of documents they 
are. Alert boxes have icons that denote the severity of the problem. 


Insertion Point 

You spent hours typing it. Now your brilliant summary and your 
sparkling introduction contradict because you forgot to type "not" on 
Page 1. Don't you wish you could just squeeze one little "not" into 
it? In a Macintosh document, you can. Clicking within text selects an 
insertion point: whatever you type next is inserted into the document 
at that point. You also can take something that you've cut or copied 
from somewhere else in your document (or some other document) and paste 
it in at the insertion point. 


Keyboard 

What's a keyboard for? Typing. Words and numbers. That's it. You 
don't have to learn to type long strings of computery phrases for the 
Macintosh: you choose all the commands with the pointer. The 
keyboard's mainly for typing your information into a document. 


Memory 

Your Macintosh has memory in which it keeps your documents and the 
programs you use to work on them. When the Macintosh is powered off, 
its memory is empty. Its only instinct when you turn its power on is 
to bring in certain programs from the disk: these programs control the 
electronic desk top. Once you see the desk top, the rest of your 
Macintosh's memory is at your disposal. You can open- a document to 
bring it into memory (along with the application that works on it), 
work on the document, and when you're finished, close the document and 
file it back onto the disk. But the Macintosh memory is limited: if 
your document gets too large for it to hold all at once, you'll have to 
break it into parts and work on the parts separately. And don't forget 
that the Macintosh's memory vanishes when you turn the power off. 
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Menu — 

The real power of the Macintosh is in the dozens and dozens of commands 
it understands. On most computers, you have to memorize these commands 
(with names only a programmer could love). The Macintosh presents all 
commands it understands in lists called menus. You choose a command 
from the list and the Macintosh follows your orders. And the Macintosh 
doesn't crowd the desk top with all those commands: it keeps them 
tucked under the menu bar. With the pointer you press on a title in 
the menu bar to make a menu appear. When you drag the pointer to the 
item you want and release the button, the menu disappears and the 
Macintosh carries out the command. 


Menu Bar 

To help you find the command you want, the Macintosh groups similar 
commands together in menus and shows the titles of all the menus in the 
menu bar, at the top of the desk top. You position the pointer on a 
title and press and hold the mouse button: the menu appears. 


Mouse ___ 

All your documents are sitting there on the Macintosh desk top. But 
you need a way to get your fingers in there without breaking the glass 
screen and making a big mess. So to make it possible to work on the 
electronic desk top (and to keep your service bills down), there’s a 
pointer on the screen that’s connected to the mouse. Moving the mouse 
on the table moves the pointer on the screen. You do most things with 
the Macintosh by positioning the pointer with the mouse and pressing 
the button on top of the mouse. 


Mouse Button 

When you've positioned the pointer over something (like information to 
select or a command to choose), you tell the Macintosh of your intent 
by pressing and releasing the button on top of the mouse. Just how you 
press it controls what you can do: to use a button or check a box, 
just click the mouse button; to move something across the desk, hold 
down the button while moving the mouse to "drag" the thing to another 
place. 


Note Pad _ . 

Inspiration comes at odd moments, usually when you’re in the middle of 
doing something else. What do you do with those fleeting thoughts 
that, if unrecorded, would be lost forever? You jot them down, of 
course. And without sharpening a pencil, you could pull the Note Pad 
desk accessory onto the desk top, and make all the notes you want 
there: it doesn't disturb what you're doing, and what you've noted 

stays around until you need the information, no matter what you're 
doing with the Macintosh. 
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Numeric Keypad • _ 

Quick number-crunchers (the people, not the machines) like to enter 
their data on a ten-key calculator pad, not a keyboard* Our numeric 
keypad has the ten digits in their familiar places, plus a few other 
keys for calculation* You can use it just like the keyboard when 
entering numbers into a document. 


Open 

On the desk top all your documents are represented by Icons. When you 
want to actually work on a document, you select it and open it. When 
you open a document you see its contents— the text and graphics that 
comprise it — through a window on the desk top. You also get an 
application to work on that document, with a menu bar full of menus of 
useful commands. When you're finished working with the document, you 
file it on the disk and close it; the window disappears and your 
document is again represented by an icon on the desk top. 


Overlapping Windows 

Just as the papers on your own desk can be stacked arid overlapped, the 
windows on the Macintosh desk top can be arranged the same way. You 
can move a window anywhere on the desk: just drag it by its title and 
drop it where you want it. If you want to see a window that’s being 
overlapped by another, just click in any portion of it that's visible: 
it'll come in front of the others. 


Pane 

A window usually shows more than just a document : it can show other 
information connected with the document, or two different parts of the 
same document. When the inside of a window is split up into different 
parts like this, each part is called a pane. 


Paste 

When people who produce newspapers or magazines need to move a piece of 
text or a picture from one page to another, they cut it out, go to that 
page, and paste it into position. That's the way you do it on the 
Macintosh, too: once you've cut (or copied) what you want to move, you 
select a place to put it, and use the paste command. The thing you're 
moving had been stored in the clipboard, and when you paste, what's In 
the clipboard replaces the current selection. 


Pointer 

You can move around, shuffle, and stack all those documents and other 
things on your Macintosh desk top just like on your own desk. But 
since you can't put your fingers through the screen to get to them, you 
use the pointer to do those things for you. The pointer is connected 
to the mouse; as you move the mouse, the pointer follows it across the 
screen. The pointer is usually shaped like an arrow, but it changes 
shape according to what's under it: an I-beam for text, a cross in 
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Gore of Explanation 


tables or cells, or an hourglass when the Macintosh is performing a 
time-consuming operation® 

Press 

You kick things off when you press the mouse button. Whatever ’s under 
the pointer starts to respond: text is highlighted, menus pull down, 
windows move to the front. But nothing really happens until you 
release the button. This way the Macintosh can tell whether you are 
clicking or dragging, and act accordingly. 


Scrolling 

A document is usually bigger than the window you see it through. So 
you only see a portion of your document in its window at a time. To 
get to another place in the document, you scroll it, moving it under 
the window until you see the information you want. You use the various 
parts of the scroll bars to scroll the document. 


Scroll Arrow • 

The two scroll arrows at the ends of a scroll bar let you move through 
a document a little at a time. 


Scroll Bar 

To help you get from one part of your document to another, most 
document windows are equipped with one or two scroll bars. Clicking 
the scroll arrows on the scroll bar moves the document under the window 
a little at a time. Clicking above or below the scroll box moves the 
document one windowful at a time. And dragging the scroll box in the 
scroll bar moves you directly to any place in the document you wish. A 
document window usually has two scroll bars : one to move vertically 
and one to move horizontally. 


Scroll Box 

Since you see only a portion of your document through a window, you 
need some indication of how that portion relates to the whole document. 
In the scroll bar is a white box: the position of that box (called the 
scroll box) in the scroll bar represents the position of the window 
over the document. 


Size Box 

Yes, your documents are usually bigger than the windows you see them 
through. And you can scroll to see different parts of the document. 
But if you really want to see more (or less) of the document, you can 
use the size box (usually in the lower-right corner of the window) to 
change the size of the window. Dragging the size box changes the 
height and width of the window, while leaving it in place on the 
desk top. So to get a window completely out of the way, you’d use the 
size box to shrink it down, and drag it by its title bar to a far 
corner of the desk top. 
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Select __ 

To do something "using the Macintosh you tell it two things 2 what ~~ 
information you want to work on, and what to do to that information. 

You tell the Macintosh what information to work on by selecting it. 

You can select a single item to work on just by positioning the pointer 
over it and clicking the mouse button. You can select a number of 
items to work on together by positioning the pointer on the first item, 
pressing the mouse button, dragging to the last item, and releasing the 
mouse button. 


Selection ________ 

Most commands you can give the Macintosh make it do something to the 
selection: one or more pieces of information that you have selected to 
work on. The selection can even be just a place where you want to put 
new information. The selected information appears highlighted, 
different from all other information. Choosing a command usually acts 
on the current selection; adding new information usually replaces the 
current selection. 


Split Bar 

No matter how large a window is, the document it's showing will 
probably be larger. So you can't see that much Information in it at 
one time. But what if you're looking at the bottom-line totals for 
your monthly expenses, but the names of the months have scrolled off 
the top and you can't tell which month is which? You can split a 
window into two panes, each showing a different part of the document, 
and scroll them independently. 


Title Bar 

Each window has a title that identifies the document it's showing. The 
title usually appears in a thin bar at the top of the window. You can 
move a window around the desk top by dragging its title bar. 


Typeface __ 

Computers are being used more and more to typeset the books, magazines, 
and newspapers you read every day. Isn't it strange that most 
computers still display and print biocky, hard-to-read type that even 
your typewriter can do better? But the Macintosh shows your documents 
in your choice of attractive proportionally-spaced fonts in a number of 
different sizes. You can add the artistry of type design to even the 
most mundane of your works. 
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The Macintosh has beautiful fonts, proportionally spaced, and well 
designed, but that's not all. Any text in any font can be put into one 
or a combination of typestyles for emphasis or other aesthetic reasons. 
Boldface type calls attention to itself. Italic type is used for 
foreign phrases, and underlining denotes book or movie titles. 

Outlined and shadowed text add distinctive titles to documents or 
drawings* 


vJhat is done can usually be undone, if you act quickly enough* Most 
changes you can make to your document — editing or formatting can be 
retracted by choosing Undo before doing anything more* Undo can fix 
only the last change you made to the document* It dosen’t remember 
minor things (like moving the window, scrolling, or selecting) that you 
can undo yourself* 


Window __ _ — — — — 

Long documents are too large to spread out on your own desk, and on the 
Macintosh desk top they'd be ridiculous* Just as you look at a 
document a page or two at a time, the Macintosh presents a reasonable 
portion of a document to you in a window* You see the document through 
the window, and using the scroll bars on the window, you can flip 
through its entire length (and breadth). 
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FIVE KEY CONCEPTS ( and two key paradigms ) 

1. The Macintosh screen is an electronic desk top, and all your 
information is in documents on the desk top. You can move objects 
anywhere on the desk top. 

2. You manipulate things on the desk top with the mouse and the 
pointer. Moving the mouse moves the pointer. Things happen when 
you position the pointer and press the mouse button. 

3. First you select the information to manipulate, then you choose a 
command to affect the selected information. 

4. Typing on the keyboard replaces the selection with what's typed. 

5. You see the information in your documents through windows. You 
can scroll to see different parts of the document through a 
window. 


Two Key Paradigms 

1. Create a document. Open a window onto it, add information, and 
edit it. Save the new version of the document. Print a paper 
copy* Close the window to work on another document. 

2. Cut some information, select an insertion point somewhere else in 
the document, and paste the information there. The last piece of 
information you cut out of the document is kept on the clipboard. 
You can carry the clipboard from one document to another. 
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FOUR COMFORTING THOUGHTS 


1. You can't hurt the Macintosh by pressing the mouse button or 
typing on the keyboard. 

2. Moving the mouse only moves the pointer: nothing happens until 
you press and release the mouse button. 

3. Most changes you make can be undone. Those that can't be undone 
warn you beforehand. 

4. Work you do on a document doesn't replace the previous version of 
the document until you explicitly save the new changes on the 
disk. 
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ABSTRACT 

This document introduces you to the Desk Manager, the part of the 
Macintosh User Interface Toolbox that handles desk accessories such as 
the Calculator. It describes the simple programmatic interface to the 
Desk Manager and tells you how to define your own desk accessories. 


Summary of significant changes and additions since last version: 

- Desk accessories should be opened from Pascal with a call to 
OpenDeskAcc rather than Q/penDriver. 

- The correction noted on 2/28 has been incorporated into the 
manual. You should call the SystemTask routine yourself, at least 
once for each call to GetNextEvent (see page 8). 

- Desk accessories can have menus that occupy the entire menu bar. 
The section on defining your own desk accessories now includes 
more details about menus (page 9). The discussion of the driver 
routines in that section has been revised (page 12). 

- A desk accessory need not be displayed in a window; it's possible 
for an accessory to have only a menu (or menus) and not a window. 
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ABOUT THIS MANUAL 


This manual describes the Desk Manager, the part of the Macintosh User 
Interface Toolbox that supports the use of desk accessories from an 
application; the Calculator, for example, is a standard desk accessory 
available to any application. *** Eventually this will become part of 
a larger manual describing the entire Toolbox. *** You'll learn how to 
use the Desk Manager routines, how to access the standard desk 
accessories, and how to define accessories of your own. 

( hand) 

This manual describes version 4 of the ROM. If you" re 
using a different version, the Desk Manager may not work 
as discussed here. 

Like all documentation about Toolbox units, this manual assumes you are 
familiar with the Macintosh User Interface Guidelines, Lisa Pascal, and 
the Macintosh Operating System's Memory Manager. You should also be 
familiar with the following: 

- The Window Manager, Menu Manager, and Event Manager. 

- The basic concepts behind the Resource Manager. 

- I/O drivers and related Operating System routines, as documented 
*** though probably not up-to-date *** in the Macintosh Operating 
System Reference Manual. 

The manual begins with an introduction to the Desk Manager and some 
background information about desk accessories including how the 
application opens them. Next, a section on using the Desk Manager 
introduces you to its routines and tells how they fit into the flow of 
your application. This is followed by the detailed descriptions of all 
Desk Manager procedures and functions, their parameters, calling 
protocol, effects, side effects, and so on. 

Following these descriptions are sections that will not interest all 
readers. Special information is given for programmers who want to 
define their own desk accessories and for those who will use the Desk 
Manager routines from assembly language. 

Finally, there's a summary of the Desk Manager routine calls, for quick 
reference, and a glossary of terras defined in this manual. *** The 
glossary has only one entry, but eventually it. will be merged with the 
glossaries from the other Toolbox documentation. The many Operating 
System terms have not been included in this glossary. *** 
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ABOUT THE DESK MANAGER 

The Desk Manager enables your application to support desk accessories , 
which are M mini“applications that can be run at the same time as a 
Macintosh application. In addition to the standard, predefined desk^ 
accessories, such as the Calculator and the Puzzle, there s a mechanism 
for defining your own accessories. 



Calculator 


B, 

tDODQB 




Active Inactive 


Figure 1. The Calculator Desk Accessory 

The Macintosh user opens desk accessories by choosing them from the 
standard Apple menu (the menu whose title is an Apple symbol). When a 
desk accessory is chosen from this menu, the accessory is displayed in 
a window on the desk top and that window becomes the active window. 



Aft accessory is chosen 
from the Apple menu. 


The accessory’s window 
appears as the active 
window. 


Figure 2. Opening a Desk Accessory 


6/14/83 Rose 


CONFIDENTIAL 


/DSKMGR/DESK.2 






ABOUT THE DESK MANAGER 5 


After being selected, the accessory may be used as long as it's active. 
The user can activate other windows and then reactivate the desk 
accessory by clicking inside it. Whenever a desk accessory is active, 
it will have a close box in its title bar. Clicking the close box 
makes the accessory disappear, and the window that's then the frontraost 
becomes active. One simple Desk Manager routine call lets your 
application handle all clicking and other user actions inside desk 
accessories . 

A desk accessory may have its own menu. When the accessory becomes 
active, the title of its menu is added to the menu bar and menu items 
may be chosen from it. A desk accessory can even have an entire menu 
bar full of its own menus; its menus will completely replace the menus 
already in the menu bar. When an accessory that has its own menu or 
menus becomes inactive, the menu bar is restored to normal. 

Although desk accessories are usually displayed in windows, this is not 
necessarily so. It's possible for an accessory to have only a menu (or 
menus) and not a window. In this case the menu will include an item to 
close the accessory. 


DESK ACCESSORIES: BACKGROUND 

— - ■ ■ — ■ - - - - • t ■ - 

A desk accessory is actually a special type of I/O driver. One of the 
ways it's special is that it may have a window associated with it. 
Normally a desk accessory is displayed in a system window of type 
systemKind (meaning, to the Window Manager, "system window other than 
dialog or alert window"). 

Desk accessories and other I/O drivers used by Macintosh applications 
are defined in resource files. Standard or shared desk accessories are 
included in the system resource file. Accessories specific to an 
application are rare; if there are any, they're defined in the 
application's resource file. 

The Menu Manager routine AddResMenu may be used to append to a given 
menu the names of all currently available desk accessories. This 
enables you to set up the Apple menu. 

The application opens a desk accessory by calling an Operating System 
routine, passing it the resource name for the accessory. The Operating 
System in turn calls a Resource Manager routine to access the desk 
accessory from the resource file. The application can get the name of 
a desk accessory that was chosen from the Apple menu by calling the 
Menu Manager routine Getltem. 

For example, a Pascal programmer wanting to open the desk accessory 
whose name is stored in the variable myString would call 

refNum := OpenDeskAcc(myS tring) ; 
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OpenDeskAcc calls OpenDriver and displays the desk, accessory s window, 
making it the active window. 

A desk accessory can be closed with the Operating System routine for 
closing an I/O driver. In Pascal, the call would look like this: 

CloseDriver( r efNum) ; 

Usually, though, the application won't close the desk accessory; 
instead, it will be closed when the user clicks its close box (or, if 
there's a menu instead of a window, when the user selects the menu item 
to close the accessory). Also, every desk accessory on the application 
heap will be deallocated when the application terminates. 


USING THE DESK MANAGER 

As discussed above, desk accessories are defined in resource files and 
opened with an Operating System routine. The primary task of the Desk 
Manager is to deal with events that occur in system windows belonging 
to desk accessories. This section introduces you to the Desk Manager 
routines and how they fit into the general flow of an application 
program. The routines themselves are described in detail in the next 
section. 


When the Event Manager routine GetNextEvent reports that a mouse down 
event has occurred, the application calls the Window Manager routine 
FindWindow to find out where the mouse button was pressed. FindWindow 
returns a pointer to the window the mouse button was pressed in and 
also a code that gives more information. One of these codes is the 
predefined constant inSysWindow, which means that the window the mouse 
button was pressed in is a system window. When FindWindow returns 
inSysWindow, the application should call the Desk Manager routine 
SystemClick, which handles mouse down events in system windows. 
SystemClick responds to some events directly and routes others to desk 
accessories, as appropriate. 

( hand) 

The application never need be concerned with exactly 
which desk accessories are currently open. 

Certain periodic actions may be defined for desk accessories; to see 
that they're performed, you need to call the SystemTask routine at 
least once for every call to GetNextEvent. 

The two remaining Desk Manager routines are never called by the 
application, but are described in this manual because they reveal inner 
mechanisms of the Toolbox that may be of interest to advanced Macintosh 
programmers. 
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DESK MANAGER ROUTINES 


This section describes all the Desk Manager procedures and functions. 
They're presented in their Pascal form; for information on using them 
from assembly language, see "Using the Toolbox from Assembly Language" 
*** doesn't exist, but see QuickDraw manual *** and also "Notes for 
Assembly-Language Programmers" in this manual. 


Handling Mouse Down Events 


PROCEDURE SystemClick (theEvent: EventRecord; theWindow: WindowPtr); 

When a mouse down event occurs and the Window Manager routine 
FindWindow reports that the mouse button was pressed in a system 
window, the application should call SystemClick with theEvent equal to 
the event record and theWindow equal to the window pointer. If the 
given window belongs to a desk accessory, SystemClick sees that the 
event gets handled properly; in the rare case that the window is a 
dialog or alert window, SystemClick does nothing. 

SystemClick determines which part of the desk accessory's window the 
mouse button was pressed in, and responds accordingly (similar to the 
way your application responds to mouse activities in other windows). 

- If the mouse button was pressed in the content region of the 
window and the window was active, SystemClick sends the mouse down 
event to the desk accessory, which processes it as appropriate. 

- If the mouse button was pressed in the content region and the 
window was inactive, SystemClick makes it the active window. 

- If the mouse button was pressed in the drag region, SystemClick 
calls the Window Manager routine DragWindow to pull an outline of 
the window across the screen and move the window to a new 
location. If the window was inactive, DragWindow also makeis it 
the active window (unless the COMMAND key was pressed along with 
the mouse button). *** The name of this key may change. *** 

- If the mouse button was pressed in the go-away region, SystemClick 

calls the Window Manager routine TrackGoAway to determine whether 
the mouse is still inside the go-away region when the click is 
completed: if so, it tells the desk accessory to close itself; if 

not, it does nothing. 
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Performing Periodic Actions 


PROCEDURE SystemTask; 

For each open desk accessory, SystemTask causes the periodic action 
defined for that accessory to be performed, if any such action has been 
defined and if the proper time period has passed since the action was 
last performed. For example, a clock accessory might be defined such 
that the second hand is to move once every second; SystemTask will 
indirectly cause the second hand to move if a second has passed since 
it last moved. 

You should call this procedure once for every call to GetNextEvent, or 
more than once if your application isn't set up so that it calls 
GetNextEvent often — for example, if it does an unusually large amount 
of processing between calls to GetNextEvent. 

( hand) „ 

Preferably SystemTask would be called at least every o{0th 

of a second. 




Advanced Routines 


FUNCTION SystemEvent (theEvent: EventRecord) : BOOLEAN; 

SystemEvent is called only by the Event Manager routine GetNextEvent 
when it receives an event, to determine whether the event should be 
handled by the application or by the system. If the given event should 
be handled by the application, SystemEvent returns FALSE; otherwise, it 
calls the appropriate system code to handle the event and returns TRUE. 

In the case of a null, abort, or mouse down event, SystemEvent does 

nothing but return FALSE. Notice that it responds this way to a mouse ^ 

down event even though the event may in fact have occurred in a system 

window (and therefore may have to be handled by the system). The 

reason for this is that the check for exactly where the event occurred 

(via the Window Manager routine FindWindow) is made later by the 

application and so would be made twice if SystemEvent were also to do 

it. To avoid this duplication, SystemEvent passes the event on to the 

application and lets it make the sole call to FindWindow. Should 

FindWindow reveal that the mouse down event did occur in a system 

window, the application can then call SystemClick., as described above, 

to get the system to handle it. 

If the given event is a mouse up, key down, key up, or auto-key event, 

SystemEvent checks whether the active window belongs to a desk 
accessory and whether that accessory can handle this type of event. 1 
so, it sends the event to the desk accessory and returns TRUE; 
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otherwise, it returns FALSE. 

If SysteraEvent is passed an activate or update event, it checks whether 
the window it occurred in is a system window belonging to a desk 
accessory. If so, it sends the event to the desk accessory and returns 
TRUE; otherwise, it returns FALSE. 

In the case of a network event, SystemEvent looks for a desk accessory 
that handles network events. If it finds one, it passes the event to 
that accessory and returns TRUE; otherwise, it returns FALSE. (It 
assumes that only one of the desk accessories will handle such events.) 

Finally, if the given event is a disk inserted event, SystemEvent does 
some low-level processing (by calling the Operating System routine 
MountVolume) but passes the event on to the application by returning 
FALSE (because the application may want to do further processing). 

PROCEDURE SystemMenu (menuResult: Longlnt); 

SystemMenu is called only by the Menu Manager routines MenuSelect and 
MenuKey, when an item in a menu belonging to a desk accessory has been 
chosen. The menuResult parameter has the same format as the value 
returned by MenuSelect and MenuKey: the menu ID in the high-order word 
and the menu item number in the low-order word. (The menu ID will be 
negative.) SystemMenu directs the desk accessory to perform the 
appropriate action for the given menu item. 


DEFINING YOUR OWN DESK ACCESSORIES 


To define your own desk accessories, you must create the corresponding 
I/O driver and include it in the system resource file or in your 
application's resource file. The resource type for I/O drivers is 
'DRVR'. The resource ID for a desk accessory is the driver's unit 
number and should be between 12 and 23 inclusive. The resource name 
should be whatever you want to appear in the Apple menu. 

( hand) 

Names beginning with a period (.) are reserved for I/O 
drivers that are not desk accessories. 

The structure of an I/O driver is described in the Macintosh Operating 
System Reference Manual. Here we will review some of that information 
and present additional details pertaining specifically to I/O drivers 
that are desk accessories. 

As illustrated in Figure 3, the I/O driver begins with a few words of 
flags and other data for the driver, followed by offsets to the 
routines that do the work of the driver, an optional title, and finally 
the routines themselves. 
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0 

Flag? /descriptor 


2 

Tick count 


4 

Event mask 


6 

Menu ID 


8 

Offset to open routine 

> 

10 

Offset to prime routine 


12 

Offset to control routine 


14 

Offset to status routine 


16 

Offset to close routine 


18 

Title length (1 byte) 


19 

Title 



k Actual code of the driver 



> 1 word each 


optional 


Figure 3. Desk Accessory I/O Driver 


( hand) 

Usually drivers are created entirely from assembly 
language, but you can use an assembly language-to-Pascal 
interface that will enable you to write the body of the 
driver routines in Pascal, An interface named ProtoOrn 
has been created for this purpose at Apple; for more 
information, see your Macintosh software coordinator. 

The first four words of the driver for a desk accessory contain the 
following : 

1. A flags/descriptor word. Bits 0 through 7 and bit 12 are relevant 
only to ROM-based drivers; they're ignored for desk accessories. 
Bits 8 through 11 are the enable flags for the driver routines. 

The following flags are especially for desk accessories: 

Flag Name Meaning if set 

bit 13 NeedsTime Driver needs time for performing a 

periodic action for the desk accessory 
bit 14 NeedsLock Driver will be locked in memory as soon 

as it's opened 

2. If the NeedsTime flag is set, a tick count indicating how often 
the periodic action should occur. A tick count of 0 means it 
should happen as often as possible, a tick count of I means it 
should happen every 60th of a second, and so on. The action 
itself is performed by the control routine in the driver when it's 
called by the SystemTask procedure. 

3. An event mask specifying which events the desk accessory can 
handle. This should especially include update events and usually 
will include mouse down events. 
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4. If the desk accessory has its own menu (or menus), the ID of the 
menu (or of any of the menus); otherwise, 0. The menu ID will be 
negative. For menus defined in resource files, it's the resource 
ID; for menus created by the desk accessory, it's any negative 
number (between -1 and -32767) that you choose to identify this 
accessory's menu. It must be different from the menu ID stored 
here for other desk accessories. 

Following these four words are the offsets to the driver routines and, 
optionally, a title for the desk accessory (preceded by its length in 
bytes). You can use the title in the driver as the title of the 
accessory's window, or just as a way of identifying the driver in 
memory . 


The Device Control Entry 

When any of the routines in the I/O driver is called, a pointer to the 
driver's Device Control Entry is passed in A1 . Most of the data in the 
Device Control Entry is stored and accessed only by the Operating 
System, but in some cases the driver routines themselves must store 
into it. The structure of the Device Control Entry, which is discussed 
in detail in the Operating System manual, is illustrated in Figure 4. 
Notice that some of the data is taken from the first four words of the 
I/O driver. 


0 

Pointer to start of driver 

long 

4 

Flags (from driver, plus 3ome dynamic flags) 

word 

6 

Driver input queue header: flags 

word 

8 

Driver input queue header: QHead 

long 

12 

Driver input queue header: QTail 

long 

16 

Position pointer (position in file) 

long 

20 

Handle to driver’s private storage 

long 

24 

Reference number for this driver 

word 

26 

Counter for SystemTask timing 

long 

30 

Pointer to driver's window 

long 

34 

Tick count (from driver) 

word 

36 

Event mask (from driver) 

word 

38 

Menu ID (from driver) 

word 


Figure 4. Device Control Entry 
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The Driver Routines 

Of the five possible driver routines, only three need to exist for desk 
accessories: the open, close, and control routines- The other 

routines (prime and status) may be used if desired for a particular 
accessory. 


The open routine opens the desk accessory. 


- If the accessory has a window, this routine creates the window 
(with the Window Manager function NewWindow) , specifying that it 
be invisible. (Remember, OpenDeskAcc takes care of displaying the 
window.) It sets the windowKind field in the window record to 
systemKind and stores the window pointer in the Device Control 
Entry. 

- It allocates the driver's private storage, if any, and stores a 
handle to it in the Device Control Entry. It might, for example, 
create a menu or menus for the accessory. 


-It initializes any local variables. 


The close routine closes the desk accessory, disposing of its window 
(if any) and replacing the window pointer in the Device Control Entry 
with NIL. If the driver has any private storage, the close routine 
also disposes of that storage. 


The action taken by the control routine depends on information passed 
in the parameter block pointed to by A0. A message is passed in the 
" op code" field (26 bytes in); this message is simply a number that 
tells the routine what action to take. There are four such messages: 


Message Name 

64 SendEvent 

65 Run 


66 Cursor 

67 Menu 


Action taken by control routine 
Handles a given event 

Takes the periodic action, if any, for 

this desk accessory 

Changes the shape of the cursor if 

appropriate 

Handles a given menu item 


Along with the SendEvent message (64) , the control routine receives an 
event pointer as a parameter (28 bytes in) . It responds by handling 
the given event in whatever way is appropriate for this desk accessory. 
SystemClick and SystemEvent call the control routine with this message 
to send the driver an event that it should handle- for example, an 
activate event that makes the desk accessory active or inactive. When 
a desk accessory becomes active, its control routine might install a 
menu in the menu bar. If the accessory becoming active has more than 
one menu, the control routine should respond as follows: 

- Store the accessory's unique menu ID in the system global 

mBarEnable . (This is the negative menu ID in the I/O driver and 
the Device Control Entry.) 
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- Call the Menu Manager routines GetMenuBar to save the current menu 
list and ClearMenuBar to clear the menu bar. 

- Install the accessory's own menus in the menu bar. 

Then, when the desk accessory becomes inactive, the control routine 
should call SetMenuBar to restore the former menu list, call 
DrawMenuBar to draw the menu bar, and set mBarEnable to 0. 

The Run message (65) tells the control routine to perform the periodic 
action for this desk accessory. For every open driver that has the 
NeedsTime flag set, the SystemTask procedure calls the control routine 
with the Run message if the proper time period has passed since the 
action was last performed. 

The cursor may have a special shape when it's inside an active desk 
accessory; the Cursor message (66) makes this possible. The control 
routine is called repeatedly with this message as long as the desk 
accessory is active. If desired, the control routine may respond by 
checking whether the mouse position is in the desk accessory's window 
and then changing the shape of the cursor if it is. 

Finally, when the Menu message (67) is sent to the control routine, the 
following information is passed as a parameter (28 bytes in) : a long 
integer containing the menu ID of the desk’ accessory's menu in the 
high-order word and a menu item number in the low-order word. The 
control routine takes the appropriate action for when the given menu 
item is chosen from the menu, and then makes the Menu Manager call 
HiliteMenu(0) to remove the highlighting from the menu bar. 


A Sample Desk Accessory 

*** to be supplied; meanwhile, see your Macintosh software coordinator 
*** 


NOTES FOR ASSEMBLY-LANGUAGE PROGRAMMERS 


Information about how to use the User Interface Toolbox from assembly 
language is given elsewhere. *** For now, see the QuickDraw manual. 
*** This section contains special notes of interest to programmers who 
will be using the Desk Manager from assembly language. 

The file named SYSEQU.TEXT contains definitions of the I/O driver data 
structures . 
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SUMMARY OF THE DESK MANAGER 


Handling Mouse Down Events - — 

PROCEDURE SystemClick (theEvent: EventRecord; theWindow: WindowPtr); 


Performing Periodic Actions 
PROCEDURE SysteraTask; 


Advanced Routines 

FUNCTION SystemEvent (theEvent: EventRecord) : BOOLEAN ; 
PROCEDURE SystemMenu (menuResult: Longlnt); 
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GLOSSARY _ 

desk accessory: A "mini-application" , implemented as an I/O driver, 
that can be run at the same time as a Macintosh application. 

tick: A 60th of a second. 
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The Dialog Manager: A Programmer's Guide /DMGR/ DIALOG 


See Also: Macintosh User Interface Guidelines 

Macintosh Operating System Reference Manual 

QuickDraw: A Programmer's Guide 

The Font Manager: A Programmer's Guide 

The Resource Manager: A Programmer's Guide 

The Event Manager: A Programmer's Guide 

The Window Manager: A Programmer's Guide 

Macintosh Control Manager Programmer's Guide 

The Desk Manager: A Programmer's Guide 

CoreEdit: A Programmer's Guide 

TextEdit: A Programmer's Guide 

Putting Together a Macintosh Application 
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ABSTRACT 

The Dialog Manager is the part of the Macintosh User Interface Toolbox 
chat supports dialog boxes and the alert mechanism. This manual tells 
you how to manipulate dialogs and alerts with Dialog Manager routines. 


Summary of significant changes and additions since last version: 

- The Return key (like Enter) now has the same effect as clicking 
the default button in an alert box. Return and Enter also have 
this effect in a modal dialog; the default button is the first 
button in the item list, normally the OK button (pages 5, 11, 22). 

- Changes have been made to the structure of a dialog record (page 
14) and a dialog template (page 28). 

- The standard sound procedure now exists. Sounds 1 through 3 are 
the corresponding number of short beeps (page 15). 

- The discussion of filterProcs for ModalDialog has changed (page 

22 ). 

- Assembly-language programmers can change the font used in dialogs 
and alerts (page L9). 


oo cr> ct> 


2 


Dialog Manager Programmer's Guide 


TABLE 

3 

4 • 

6 


11 

12 

12 

13 

13 

14 

15 

16 
17 

17 

18 
2(3 
23 
25 

27 

28 
29 
3(3 
3(3 

31 

32 
34 
38 


OF CONTENTS 

About This Manual 
About the Dialog Manager 
Dialog and Alert Windows 
Dialogs, Alerts, and Resources 
Item Lists in Memory 
Item Types 

Item Handle or Procedure Pointer 
Display Rectangle 
Item Numbers 
Dialog Records 
Dialog Pointers 
The DialogRecord Data Type 
Alerts 

Using the Dialog Manager 
Dialog Manager Routines 
Initialization 

Creating and Disposing of Dialogs 
Handling Dialog Events 
Invoking Alerts 

Manipulating Items in Dialogs and Alerts 
Modifying Templates in Memory 
Dialog Templates in Memory 
Alert Templates in Memory 
Formats of Resources for Dialogs and Alerts 
Dialog Templates in a Resource File 
Alert Templates in a Resource File 
Items Lists in a Resource File 
Summary of the Dialog Manager 
Glossary 


Copyright (c) 1983 Apple Computer, Inc. All rights reserved. Distributi 
in limited quantities does not constitute publication. 



ABOUT THIS MANUAL 


3 


ABOUT THIS MANUAL 


This manual describes the Dialog Manager of the Macintosh User 
Interface Toolbox# *** Eventually it will become part of a 
comprehensive manual describing the entire Toolbox and Operating 
System. *** The Dialog Manager provides Macintosh programmers with 
routines for implementing dialog boxes and the alert mechanism, two 
means of communication between the application and the end user. 

(hand) 

This manual describes version 7 of the ROM. If you’re 
using a different version, the Dialog Manager may not 
work as discussed here. 

Like all documentation about Toolbox units, this manual assumes you’re 
familiar with the Macintosh User Interface Guidelines, Lisa Pascal, and 
the Macintosh Operating System’s Memory Manager. You should also be 
familiar with the following: 

* The basic concepts and structures behind QuickDraw, particularly 
rectangles, grafPorts, and pictures. 

“ The basic concepts behind TextEdit or CoreEdit, to understand 
editing text in dialog boxes. 

• Resources, as discussed in the Resource Manager manual. 

- The Toolbox Event Manager, the Window Manager, and the Control 
Manager. 

This manual is intended to serve the needs of both Pascal and 
assembly-language programmers. Information of interest to 
assembly-language programmers only is isolated and labeled so that 
Pascal programmers can conveniently skip it. *** Some of that 
information refers to the ’’Toolbox equates” file (ToolEqu.Text ) , which 
the reader will have learned about in an earlier chapter of the final 
comprehensive manual. *** 

The manual begins with an introduction to the Dialog Manager and what 
you can do with it. It then discusses the basics of dialogs and 
alerts: their relationship to windows, their relationship to 

resources, and the information stored In memory for the items in a 
dialog or alert. Following this is a discussion of the dialog record, 
where the Dialog Manager keeps all the information it needs about a 
dialog, and an overview of how alerts are handled. 

Next, a section on using the Dialog Manager Introduces its routines and 
tells how they fit into the flow of your application. This is followed 
by detailed descriptions of all Dialog Manager procedures and 
functions, their parameters, calling protocol, effects, side effects, 
and so on. 
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Following these descriptions are sections that will not interest all 
readers. There's a discussion of how to modify definitions of dialogs 
and alerts after they've been read from a resource file, and a section 
that gives the exact formats of resources related to dialogs and 
alerts • 

Finally, there's a summary of the Dialog Manager, for quick reference, 
followed by a glossary of terms used in this manual. 


ABOUT THE DIALOG MANAGER 


The Dialog Manager is a topi for handling dialogs and alerts in a way 
that's consistent with the Macintosh User Interface Guidelines. 

A dialog box appears on the screen when a Macintosh application needs 
more information to carry out a command. As shown in Figure 1, it 
typically resembles a form on which the user checks boxes and fills in 
blanks. 


Print the document 


( Cancel ) 

® 8 1/2- h 1 r paper 

O 8 1/2“ h 14* paper 

C OK ) 

El Stop printing after each page 

Titles: Annual Report 





Figure I. A Typical Dialog Box 


By convention, a dialog box comes up slightly below the menu bar, is a 
bit narrower than the screen, and is centered between the left and 
right edges of the screen* It may contain any or all of the following: 

- Informative or instructional text 

~ Rectangles in which text may be entered (initially blank or 
containing default text that can be edited) 

- Controls of any kind 

• Graphics (icons or QuickDraw pictures) 

- Anything else, as defined by the application 

The user provides the necessary information in the dialog box, such as 
by entering text or clicking a check box. There's usually a button 
marked "OK" to tell the application to accept the information provided 
and perform the command, and a button marked "Cancel" to cancel the 
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command* Some dialog boxes contain more than one button that will 
perform the command, each in a different way* 

Most dialog boxes require the user to respond before doing anything 
else. Clicking a button to perform or cancel the command makes the box 
go away; clicking outside the dialog box only causes a beep from the 
Macintosh’s speaker. This type is called a modal dialog box because it 
puts the user in the state or "mode" of being able to work only inside 
the dialog box. It usually has the same general appearance as shown in 
Figure 1. One of the buttons in the dialog box may be outlined boldly. 
Pressing the Return key or the Enter key has the same effect as 
clicking the outlined button or, if none, the OK button; the particular 
button whose effect occurs is called the dialog’s default button and is 
the preferred ("safest") button to use in the current situation. If 
there’s no boldly outlined or OK button, pressing Return or Enter will 
by convention have no effect. 

Other dialog boxes do not require the user to respond before doing 
anything else; these are called modeless dialog boxes. The user can, 
for example, do work in document windows on the desktop before clicking 
the appropriate button in the dialog box. Clicking the Cancel button 
in this type of dialog box always makes the box go away, but clicking 
the OK button may not: it may keep the box around so that the command 
can be performed again. A modeless dialog box looks exactly like a 
document window, as illustrated in Figure 2. 


Find tent: 


Change tos 


Guide Lines 


guidelines 


( Cancel ) 
( Change flU ) 
(Change Next) 


Figure 2. A Modeless Dialog Box 

Dialog boxes may in fact require no response at all. For example, 
while an application is performing a time-consuming process, it can 
.‘display a dialog box that contains only a message telling what it’s 
'‘doing; then, when the process is complete, it can simply remove the 
dialog box. 

The alert mechanism provides applications with a means of reporting 
errors or giving warnings. An alert box is similar to a modal dialog 
box, but it appears only when something has gone wrong or must be 
brought to the user's attention. Its conventional placement is 
slightly farther below the menu bar than a dialog box. To assist the 
user who isn't sure how to proceed when an alert box appears, the 
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preferred button to use in the current situation is outlined boldly so 
it stands out from the other buttons in the alert box (see Figure 3). 
The outlined button is also the alert's default button; if the user 
presses the Return key or the Enter key, the effect Is the same as 
clicking this button. 




CAUTION 


Are you sure 
you want to erase all 
changes to your document? 


IT Cancel 

c 


OK ) 


Figure 3. A Typical Alert Box 

There are three standard kinds of alert — Stop, Note, and Caution each 
indicated by a particular icon in the top left corner of the alert box. 
Figure 3 illustrates a Caution alert. The icons identifying Stop and 
Note alerts are similar; instead of a question mark, they show an 
exclamation point and an asterisk, respectively. Other alerts can have 
anything in the the top left corner, including blank space if desired. 

The alert mechanism also provides another type of signals sound from 
the Macintosh’s speaker. The application can base its response on the 
number of consecutive times an alert occurs; the first time, it might 
simply beep, and thereafter it may present an alert box. The sound is 
not limited to a single beep. but may be any sequence of tones, and may 
occur either alone or along with an alert box. As an error is 
repeated, there can also be a change in which button is the default 
button (perhaps from OK to Cancel). You can specify different 
responses for up to four occurrences of the same alert. 

With Dialog Manager routines, you can create dialog boxes or invoke 
alerts. The Dialog Manager gets most of the descriptive information 
about the dialogs and alerts from resources in a resource file. You 
use a program such as the Resource Editor *** eventually *** to store 
the necessary information in the resource file. The Dialog Manager 
calls the Resource Manager to read what it needs from the resource file 
into memory as necessary. In some cases you can modify the information 
after it’s been read into memory. 


DIALOG AND ALERT WINDOWS 


A dialog box appears in a dialog window . When you call a Dialog 
Manager routine to create a dialog, you supply the same information as 
when you create a window with a Window Manager routine. For example, 
you supply the window definition ID, which determines how the window 
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looks and behaves, and a rectangle that becomes the portRect of the 
window’s grafPort. You specify the window’s plane (which, by 
convention, should initially be the frontmost) and whether the window 
is visible or invisible* The dialog window is created as specified. 

You can manipulate a dialog window just like any other with Window 
Manager or QuickDraw routines, showing it, hiding it, moving it, 
changing its size or plane, or whatever — all, of course, in conformance 
with the Macintosh User Interface Guidelines. The Dialog Manager 
observes the clipping region of the dialog window’s grafPort, so if you 
want clipping to occur, you can set this region with a QuickDraw 
routine. 


Similarly, an alert box appears in an alert window . You don’t have the 
same flexibility in defining and manipulating an alert window, however. 
The Dialog Manager chooses the window definition ID, so that all alert 
windows will have the standard appearance and behavior. The size and 
location of the box are supplied as part of the definition of the alert 
and are not easily changed. You don’t specify the alert window’s 
plane; it always comes up in front of all other windows. Since an 
alert box requires the user to respond before doing anything else, and 
the response makes the box go away, the application doesn’t do any 
manipulation of the alert window. 


Figure 4 illustrates a document window, dialog window, and alert 
window, all overlapping on the desktop. Note that if a dialog or alert 
window comes up while a document window is active, the document window 
becomes inactive; as shown in Figure 4, any scroll bars or size box in 
the document window disappear until the window becomes active again. 



Menu bar and desktop 


Document window on desktop 



Dialog window 
in front of document window 


Alert window 
in front of dialog window 


Figure 4. Dialog and Alert Windows 
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DIALOGS, ALERTS , AND RESOURCES ' 

To create a dialog, the Dialog Manager needs the same information about 
the dialog window as the Window Manager needs when it creates a new 
window: the window definition ID along with other information specific 

to this window* The Dialog Manager also needs to know what items the 
dialog box contains* You can store the needed information as a 
resource in a resource file and pass the resource ID to a function that 
will create the dialog* This type of resource, which is called a 
dialog template . Is analogous to a window template, and the function, 
GetNewDialog , is similar to the Window Manager function GetNewWindow* 
The Dialog Manager calls the Resource Manager to read the dialog 
template from the resource file* It then incorporates the information 
in the template into a dialog data structure in memory, called a dialog^ 
record * 

Similarly, the data that the Dialog Manager needs to create an alert is 
stored in an alert template in a resource file* The various routines 
for invoking alerts require the resource ID of the alert template as a 
parameter* 

The information about all the items (text, controls, or graphics) in a 
dialog or alert box is stored in an item list in a resource file* The 
resource ID of the item list is included in the dialog or alert 
template. The item list in turn contains the resource IDs of any icons 
or QuickDraw pictures in the dialog or alert box, and possibly the 
resource IDs of control templates for controls in the box* After 
calling the Resource Manager to read a dialog or alert template into 
memory, the Dialog Manager calls it again to read in the item list, and 
again to read in any individual items as necessary. 

( hand ) 

To create dialog or alert templates and item lists and 
store them in resource files, you can use the Resource 
Editor *** eventually (for now, the Resource Compiler, as 
described in the manual '’Putting Together a Macintosh 
Application") ***. The Resource Editor relieves you of 
having to know the exact format of these resources, but 
for interested programmers this information is given in 
the section "Formats of Resources for Dialogs and 
Alerts". 

If desired, the application can gain some additional flexibility by 
calling the Resource Manager directly to read templates, item Lists, or 
items from a resource file. For example, you can read in a dialog or 
alert template directly and modify some of the information in it before 
calling the routine to create the dialog or alert* Or, as an 
alternative to using a dialog template, you can read in a dialog's item 
list directly and then pass a handle to it along with other information 
to a function that will create the dialog (NewDialog, analogous to the 
Window Manager function NewWindow)* 
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( hand ) 

The use of dialog templates is recommended wherever 
possible; like window templates, they isolate descriptive 
information from your application code for ease of 
modification or translation to foreign languages. 


ITEM LISTS IN MEMORY 


This section discusses the contents of an item list once it's been read 
into memory from a resource file and the Dialog Manager has sec it up 
as necessary to be able to work with it. 

An item list in memory contains the following information for each 
item: 

- The type of item. This includes not only whether the item is a 
control, text, or whatever, but also whether the Dialog Manager 
should return to the application when the item is clicked. 

- A handle to the item or, for special application-defined items, a 
pointer to a procedure that draws the item. 

- A display rectangle , which determines the location of the item 
within the dialog or alert box. 

These are discussed below along with item numbers , which identify 
particular items in the item list. 

There's a Dialog Manager procedure that, given a pointer to a dialog 
record and an item number, sets or returns that item's type, handle (or 
procedure pointer), and display rectangle. 


Item Types 


The item type is specified by a predefined constant or combination of 
constants, as listed below. Figure 5 Illustrates some of these item 
types. 


11/16/83 Rose 


CONFIDENTIAL 


/DMGR/ DIALOG. 2 


10 


Dialog Manager Programmer's Guide 


Ctrl Item 
+ radCtrl 

Ctrl Item 
+ chkCtrl 


uaerltem 
+ itemDisable 


iconltem statText 

+ itemDiseble + itemDiseble 


Ctrl Item 
+ btnCtrl 


4 = 


* 


^1 Print the document ( Cancel^ 

i • • ~i . 

-»@8 1/2“ h tl" paper ' — — — ' 

-♦O 8 1/2* h 14“ paper 

■*0 Stop printing after each page 


Titles Annual Report 


Progress of printing 


editText 


Figure 5. Item Types 


Item type 
ccrlltem+btnCtrl 

Meaning 

A standard button control. 

ctrlltenrt-chkCtrl 

A standard check box control. 

ctrlltera+radCtrl 

A standard "radio button" control. 

ctrllcem-t-resCtrl 

A control defined in a control template in a 
resource file. 

statText 

Static text; text that cannot be edited. 

editText 

(Dialogs only) Text that can be edited; the 
Dialog Manager accepts text typed by the user 
and allows editing. 

iconltem 

An icon (a 32-by-32 bit image). 

picltem 

A QuickDraw picture. 

userltem 

(Dialogs only) An application-defined item, 
such as a picture whose appearance changes. 

iteraDisable-Kany 
of Che above> 

The item is disabled (the Dialog Manager 
doesn't report events involving this item). 


The text of an editText item may initially be either default text or 
empty. Text entry and editing is handled in the conventional way, as 
in TextEdit and CoreEdit (in fact, the Dialog Manager calls TextEdit to 
handle it): 
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- Clicking in the item displays a blinking vertical bar, indicating 
an insertion point where text may be entered* 

- Dragging over text in the item selects that text, and 
double-clicking selects a word; the selection is inversely 
highlighted and is replaced by what the user then types. 

- Clicking or dragging while holding down the Shift key extends or 
shortens the current selection. 

- The Backspace key deletes the current selection or the character 
preceding the insertion point. 

The Tab key advances to the next editText item in the item list 
(wrapping around to the first if there aren’t any more). In an alert 
box or a modal dialog box (regardless of whether it contains an 
editText item), the Return key or Enter key has the same effect as 
clicking the default button; for alerts, the default button is 
identified in the alert template, whereas for modal dialogs it’s always 
the first item in the item list. 

If itemDisable is specified for an item*, the Dialog Manager doesn’t let 
the application know about events involving that item. For example, 
you may not have to be informed every time the user enters or edits 
text in an editText item, but may only need to look at the text when 
the OK button is clicked. In this case, the editText item would be 
disabled. Standard buttons and check boxes should always be enabled, 
so your application will know when they’ve been clicked. 

(eye) 

Don’t confuse disabling a control with making one 
’’inactive” with the Control Manager procedure 
Hili teControl : When you want a control not to respond at 
all to being clicked, you make it inactive. 


Item Handle or Procedure Pointer 


The item list contains the following information for the various types 
of items: 


Item type 

any Ctrl Item 

statText 

editText 

iconltem 

picltem 

userltem 


Contents 

A control handle 
A handle to the text 

A handle to the current text 

A handle to the icon 

A picture handle 
A procedure pointer 


The procedure for a userltem draws the Item; for example, if the item 
is a clock, it will draw the clock with the current time displayed. 
When this procedure is called, the current port is the dialog window’s 
grafPort. The procedure has two parameters: 
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- A windowPtr to the dialog window. In case the procedure draws in 
more than one dialog window, this parameter tells it which one to 
draw in. 

- The item number. In case the procedure draws more than one item, 
this parameter tells it which one to draw. 


Display Rectangle _ 

Each item in the item list is displayed within its display rectangle. 
Icons and QuickDraw pictures are scaled to fit the display rectangle. 

If the procedure for a userltem draws outside the item's display 
rectangle, the drawing is clipped to the display rectangle. 

(eye) 

Clicking anywhere within the display rectangle is 
considered a click of that item. 

A rectangle is drawn just outside the display rectangle around each 
editText item. When a statText or editText item is displayed, the text 
is clipped to the display rectangle arid word wrap occurs as in 
TextEdit. 


Item Numbers 


Each item in an item list is identified by an item number, which is 
simply the index of the item in the list (starting from 1). By 
convention, the first item in an alert's item list should be the OK 
button (or, if none, then one of the buttons that will perform the 
command) and the second item should be the Cancel button. The Dialog 
Manager provides predefined constants equal to the item numbers for OK . 
and Cancel: 

CONST OK - 1; 

Cancel » 2; 

In a modal dialog's Item list, the first item is assumed to be the 
dialog's default button; if the user presses the Return key or Enter 
key, the Dialog Manager normally returns Item number 1, just as when 
that item is actually clicked. To conform to the Macintosh User 
Interface Guidelines, the application should boldly outline the 
dialog's default button if it isn't the OK button. The best way to do 
this is with a userltem. To allow for changes in the default button's 
size or location, the userltem should identify which button to outline 
by its item number and then use that number to get the button's display 
rectangle . 

(eye) 

If the first item in a modal dialog's item list isn't an 
OK button and you don't boldly outline it, you should set 
up the dialog to ignore Return and Enter. To learn how 
to do this, see ModalDialog under "Handling Dialog 
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Events" in the "Dialog Manager Routines" section. 


DIALOG RECORDS 


To create a dialog, you pass information to the Dialog Manager in a 
dialog template and in individual parameters, or only in parameters; in 
either case, the Dialog Manager incorporates the information into a 
dialog record. The dialog record contains the window record for the 
dialog window, a handle to the dialog's item list, and^ some additional 
fields. The Dialog Manager creates the dialog window by calling the 
Window Manager function NewWindow and then setting the window class in 
the window record to indicate that it's a dialog window. The routine 
that creates the dialog returns a pointer to the dialog record, which 
you use thereafter to refer to the dialog in Dialog Manager routines or 
even in Window Manager or QuickDraw routines (see "Dialog Pointers" 
below). The Dialog Manager provides routines for handling events in 
the dialog window and disposing of the dialog when you're done. 

The data type for a dialog record is called DialogRecord • You can do 
all the necessary operations on a dialog without accessing the fields 
of the dialog record directly; for advanced programmers, however, the 
exact structure of a dialog record is given under "The DialogRecord 
Data Type" below. 


Dialog Pointers . 

There are two types of dialog pointer, DialogPtr and DialogPeek, 
analogous to the window pointer types WindowPtr and WindowPeek. Most 
users will only need to use DialogPtr. 

The Dialog Manager defines the following type of dialog pointer: 

TYPE DialogPtr * WindowPtr; 

It can do this because the first thing stored in a dialog record is the 
window record for the dialog window. This type of pointer can be used 
to access fields of the window record or can be passed to Window 
Manager routines that expect window pointers as parameters. Since the 
WindowPtr data type is itself defined as GrafPtr, this type of dialog 
pointer can also be used to access fields of the dialog window's 
grafPort or passed to QuickDraw routines that expect pointers to 
grafPorts as parameters. 

In some cases, a more direct way of accessing the dialog record may be 
desired. For this reason, the Dialog Manager also defines the 
following type of dialog pointer: 

TYPE DialogPeek * "DialogRecord; 

Programmers who want to access the dialog record fieLds directly must 
use this type of pointer. 
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Assembly-language note : From assembly language, of course, 
there's no type checking on pointers, and the two types of 
pointer are equal* 


The DialogRecord Data Type 

For those who want to know more about the data structure of a dialog 
record, the exact structure is given here* 

TYPE DialogRecord - RECORD 

window: WindowRecord ; 

items: Handle; 

textH: TEHandle; 

edit Field: INTEGER; 
edi tOpen : INTEGER; 
aDefltem: INTEGER 

END; 

The window field contains the window record for the dialog window* The 
items field contains a handle to the item list for the dialog. 

(hand) 

Remember that to get or change information about an item 
in a dialog, you pass the dialog pointer and the item 
number to a Dialog Manager procedure* You will never 
access information directly through the handle to the 
item list. 

The Dialog Manager uses the next three fields when text is being 
entered or edited in an editText item. The textH field contains the 
handle TextEdit uses; the data type 'TEHandle. is defined in TextEdit. 
EditField is 1 less than the item number of the editText item. The 
editOpen field is used internally by the Dialog Manager. 

The aDefltem field is used for modal dialogs and alerts, which are 

treated internally as special modal dialogs. It contains the Item 

number of the default button. The default button for a modal dialog is 
the first Item in the item list, so this field contains 1 for modal 

dialogs. The default button for an alert is specified in the alert 

template; see the following section for more information. 


Assembly— language note : The Toolbox equates file includes 
dWindLen, the length of a dialog record in bytes. 
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ALERTS 


When you call a Dialog Manager routine to invoke an alert, you pass it 
the resource ID of the alert template, which contains the following: 

- A rectangle, given in global coordinates, which determines the 
alert window's size and location. It becomes the portRect of the 
window's grafPort. To allow for the menu bar and the border 
around the portRect, the top of the rectangle should be at least 
25 pixels below the top of the screen. 

- The resource ID of the item list for the alert. 

- Information about exactly what should happen at each stage of the 
alert . 

There are four stages to every alert: the first three stages 
correspond to the first three (consecutive) occurrences of the alert, 
and the fourth stage corresponds to the fourth occurrence and any 
beyond the fourth. The actions for each stage are specified by the 
following three pieces of information: 

- Which is the default button — the OK button (or, if none, a button 
that will perform the command) or the Cancel button 

- Whether the alert box is* to be drawn 

- Which of four sounds should be emitted at this stage of the alert 

The alert sounds are determined by a sound procedure that emits one of 
up to four tones or sequences of tones. The sound procedure has one 
parameter, an integer from 0 to 3. It can emit any sound for each of 
these numbers, which identify the sounds in the alert template. If you 
don't write your own sound procedure, sound number 0 represents no 
sound and sound numbers 1 through 3 represent the corresponding number 
of short beeps, each of the same pitch and duration. For example, if 
the second stage of an alert is to cause a beep and no alert box, you 
can just specify boxDrawn*FALSE and sound*l for tftat stage in the alert 
template. If instead you want two successive beeps of different pitch, 
for example, you need to write a procedure that will emit that sound 
for a particular sound number, and specify that number in the alert 
template. See the Sound Manager manual *** (doesn't yet exist) *** for 
information about how to write a procedure that emits sound. 

( hand ) 

When the Dialog Manager detects a click outside an alert 
box or a modal dialog box, it emits sound number I; thus, 
for consistency with the Macintosh User Interface 
Guidelines, sound number 1 should always be a single 
beep. 

Internally, alerts are treated as special dialogs. The alert routine 
creates the alert window by calling NewDialog. The Dialog Manager 
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works from Che dialog record created by NewDialog, just as when it 
operates on a dialog window, but it disposes of the window before 
returning to the application. Normally your application will not 
access the dialog record for an alert; however, there is a way that 
this can happen: for any alert, you can specify a procedure that will 
be executed repeatedly during the alert, and this procedure may access 
the dialog record. For details, see the alert routines under "Invoking 
Alerts" in the "Dialog Manager Routines" section. 


USING THE DIALOG MANAGER 

This section discusses how the Dialog Manager routines fit into the 
general flow of an application program and gives you an idea of which 
routines you'll need to use. The routines themselves are described In 
detail in the next section. 

Before using the Dialog Manager, you should initialize QuickDraw, the 
Font Manager, the Window Manager, the Menu Manager, and TextEdit, in 
that order. The first Dialog Manager routine to call is InitDialogs, 
which initializes the Dialog Manager. 

Where appropriate in your program, call NewDialog or GetNewDlalog to 
create any dialogs you need. Usually you'll call GetNewDlalog, which 
takes descriptive information about the dialog from a dialog template 
in a resource file. You can instead pass the information in individual 
parameters to NewDialog. In either case, you can supply a pointer to 
the storage for the dialog record or let it be allocated by the Dialog 
Manager. When you no longer need a dialog, you'll usually call 
CloseDialog if you supplied the storage, or DisposDialog if not. 

In most cases, you probably won't have to make any changes to the 
dialogs from the way they're defined in the resource file. However, if 
you should want to modify an item in a dialog, you can call GetDItem to 
get the information about the item and SetDItem to change it. In 
particular, SetDItem is the routine to use for installing an 
application-defined item. There are also two procedures specifically 
for accessing or setting the content of a text item in a dialog box: 
GetIText and SetIText. 

If your application includes any modeless dialog boxes, call 
IsDialogEvent to learn whether an event has occurred that needs to be 
handled as part of a dialog, and then call DialogSelect if so. After 
putting up a modal dialog box, just call ModalDialog. 

Mouse activity in an editText item causes an insertion point to be 
displayed or text to be selected accordingly. Your application may 
want to bring up a dialog box with an editText item already selected, 
or to cause an insertion point or text selection to appear after the 
user has made an error in entering text. The SellText procedure lets 
the application do this. 
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For alerts, if you want other sounds besides the standard ones (up to 
three short beeps), write your 1 own sound procedure and call ErrorSound 
to make it the current sound procedure* To invoke a particular alert, 
call one of the alert routines: StopAlert, NoteAlert, or CautionAlert 
for one of the standard kinds of alert, or Alert for an alert defined 
to have something other than a standard icon (or nothing at all) in its 
top left corner. If you’re going to invoke an alert when the resource 
file might not be accessible, first call CouldAlert, which will make 
the alert template and related resources unable to be purged from 
memory; you can later make them purgeable again by calling FreeAlert. 

Finally, in either dialogs or alerts, you can substitute text in 
statT^ext items with text that you specify in the ParamText procedure. 
This means, for example, that a document name supplied at execution 
time can appear in an error message. 


DIALOG MANAGER ROUTINES 


This section describes all the Dialog Manager procedures and functions. 
They're presented in their Pascal form; for information on using them 
from assembly language, see "Using the Toolbox from Assembly Language" 
*** doesn't exist, but see "Using QuickDraw from Assembly Language" in 
the QuickDraw manual ***• 


Initialization 


PROCEDURE InitDialogs (restartProc: ProcPtr); 

Call InitDialogs once before all other Dialog Manager routines, to 
initialize the Dialog Manager. 

- It sets a pointer to a fail-safe procedure as specified by 
restartProc; this pointer will be accessed when a system error 
(such as running out of memory) occurs. RestartProc should point 
to a procedure that will restart the application after a system 
error. If no such procedure is desired, pass NIL as the 
parameter. 


Assembly-language note : The Dialog Manager stores the address 
of the fail-safe procedure in a system global named restProc. 


- It installs the standard sound procedure, which associates sound 
number 0 with no sound and sound numbers 1 through 3 with the 
corresponding number of short beeps. 
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- It passes empty strings to ParamText (described below under 
"Manipulating Items in Dialogs and Alerts"). 


PROCEDURE ErrorSound (soundProc: ProcPtr); 

ErrorSound sets the sound procedure for dialogs and alerts to the 
procedure pointed to by soundProc. The sound procedure should have one 
parameter, an integer from 0 to 3; these numbers identify the sounds 
(such as in the stages field of an alert template). 

(hand) 1 

So that the dialog and alert routines will respond to 
mouse activity in a way that conforms to the Macintosh 
User Interface Guidelines (as described below), sound ^ 

number 1 should always be a single beep. 

If you don't call ErrorSound, the Dialog Manager uses a standard sound 
procedure that causes sound number 0 to represent no sound and sound 
numbers 1 through 3 to be the corresponding number of short beeps. If 
you pass NIL for soundProc, there will be no sound at all for sound 
numbers 0 through 3. 


Assem bly-language note : The address of the sound procedure 
being used is stored in the system global daBeeper. 


Creating and Disposing of Dialogs 


FUNCTION NewDialog (dStorage: Ptr; boundsRect: Rect; title: Str255; 

visible: BOOLEAN; procID: INTEGER; behind: WindowPtr; 
go Away Flag : BOOLEAN; refCon: Longlnt; items: Handle) : 
DialogPtr; 

NewDialog creates a dialog as specified by its parameters and returns a 
pointer to the new dialog. The first eight parameters (dStorage 
through refCon) are passed to the Window Manager function NewWindow, 
which creates Che dialog window; the meanings of these parameters are 
summarized belqiw. The items parameter is a handle to the dialog's item 
list. You can get the items handle by calling the Resource Manager to 
read the item list from the resource file into memory. 

( hand ) 

Advanced programmers can create their own item lists in 
memory rather than have them read from a resource file. 

DStorage is analogous to the wStorage parameter of NewWindow; it's, a 
pointer to the storage to use for the dialog record. If you pass NIL 
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for dStorage, the dialog record will be allocated on the heap. 

BoundsRect, a rectangle given in global coordinates, which determines 
the dialog window’s size and location. It becomes the portRect of the 
window's grafPort. Remember that the top of this rectangle should be 
at least 25 pixels below the top of the screen for a modal dialog, to 
allow for the menu bar and the border around the portRect, and at least 
40 pixels below the top of the screen for a modeless dialog, to allow 
for the menu bar and the window's title bar. 

Title is the dialog window's title. If the window has a title bar, 
this title appears in it, centered and in the system font and system 
font size. 

If the visible parameter is TRUE, the dialog window is drawn on the 
screen. If it's FALSE, the window is initially invisible and may later 
be shown with a call to the Window Manager procedure ShowWindow. 

ProcID is the window definition ID, which leads to the window 
definition function for this type of window. The window definition IDs 
for the standard types of dialog window are dBoxProc for the modal type 
and documentProc for the modeless type. 

The behind parameter specifies the window behind which the dialog 
window is to be placed on the desktop. You should pass POINTER(-l) for 
this parameter to bring up the dialog window in front of all other 
windows . 

If goAwayFlag is TRUE, the dialog window has a close box in its title 
bar (if any) when the window is active. 

RefCon is the dialog window's reference value, which the application 
may store into and access for any purpose. 

NewDialog also secs the font of the dialog window's grafPort to the 
system font and sets the window class in the window record to indicate 
a dialog window. 


Assembly-language note : NewDialog actually sets the font to the 
font number stored in the system global dlgFont. If you want a 
different font to be used in a dialog box, you can set dlgFont 
to the desired font number before creating the dialog. 


FUNCTION GetNewDialog (dialogID: INTEGER; dStorage: Ptr; behind: 
WindowPtr) : DialogPtr; 

Like NewDialog (above), GetNewDialog creates a dialog as specified by 
its parameters and returns a pointer to the new dialog. Instead of 
having the parameters boundsRect, title, visible, procID, goAwayFlag, 
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and refCon, GetNewDialog has a single dialogID parameter, where 
dialogID is the resource ID of a dialog template that supplies the same 
information as those parameters. The dialog template also contains the 
resource ID of the dialog's item list. After calling the Resource 
Manager to read the item list into memory (if it's not already in 
memory), GetNewDialog makes a copy of the item list and uses that copy; 
thus you may have multiple independent dialogs whose items have the 
same types, locations, and initial contents. The dStorage and behind 
parameters of GetNewDialog have the same meaning as in NewDialog. 


PROCEDURE Close Dialog (theDialog: DialogPtr); 

CloseDialog removes theDialog' s window from the screen and deletes it 
from the window list, just as when the Window Manager procedure 
CloseWindow is called. It returns to the heap the storage used by all 
data structures associated with the dialog window (such as the window 
regions) and all the items in the dialog's item list (except for 
pictures and icons, which might be shared resources). It does not 
dispose of the dialog record or the item list itself. Call this 
procedure when you're done with a dialog if you supplied NewDialog or 
GetNewDialog with a pointer to the dialog storage (in the dStorage 
parameter) when you created the dialog. 

( hand ) 

Even if you didn't supply a pointer to the dialog 
storage, you may want to call CloseDialog if you created 
the dialog with NewDialog. You would call CloseDialog if 
you wanted to keep the item list around (since, unlike 
GetNewDialog, NewDialog does not use a copy of the item 
list). 


PROCEDURE DisposDialog (theDialog: DialogPtr); 

DisposDialog calls CloseDialog (above) and then disposes of the 
dialog's item list and dialog record. Call this procedure when you're 
done with a dialog if you let the dialog record be allocated on the 
heap when you called NewDialog or GetNewDialog (by passing NIL as the 
dStorage parameter). 


Handling Dialog Events 


FUNCTION IsDialogEvent ( theEvent : EventRecord) : BOOLEAN; 

If your application includes any modeless dialogs, call IsDialogEvent 
after calling the Toolbox Event Manager function GetNextEvent. Pass 
the current event in theEvent. IsDialogEvent determines whether 
theEvent needs to be handled as part of a dialog. If theEvent is an 
update or activate event in a dialog window, a mouse down event in the 
content region of an active dialog window, or any other type of event 
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when a dialog window is active, IsDialogEvent returns TRUE; otherwise, 
it returns FALSE. When TRUE is returned, the application should check 
whether the event is one that should not in fact be handled as part of 
a dialog, such as a key down event with the Command key held down: if 
so, it should ignore the event; otherwise, it should pass the event to 
DialogSelect (below). 


FUNCTION DialogSelect (theEvent: EventRecord; VAR theDialog: DialogPtr; 
VAR itemHit: INTEGER) : BOOLEAN; 

After learning from IsDialogEvent that the current event needs to be 
handled as part of a modeless dialog, pass the event to DialogSelect. 
DialogSelect handles the event as described below. If the event 
involves an enabled dialog Item, DialogSelect returns a function result 
of TRUE with the dialog pointer in theDialog and the item number in 
itemHit; otherwise, it returns FALSE with theDialog and itemHit 
undefined. Normally when DialogSelect returns TRUE, you'll do whatever 
is appropriate as a response to the event, and when it returns FALSE 
you'll do nothing. 

If the event is an activate or update event in a dialog window, 
DialogSelect activates or updates the window and returns FALSE. 

If the mouse button is pressed in an editText item, DialogSelect 
responds to the mouse activity as appropriate (displaying an insertion 
point or selecting text). If a key down event occurs and there's an 
editText item, text entry and editing are handled in the standard way 
for such items. In either case, DialogSelect returns TRUE if the item 
is enabled or FALSE if it's disabled. If a key down event occurs when 
there's no editText item, DialogSelect returns FALSE. 

(hand) 

To treat a typed character in a special way (such as 
ignore it, or make it have the same effect as another 
character or as clicking a button), the application 
should test for a key down event with that character 
before calling DialogSelect. 

If the mouse button is pressed in a control, DialogSelect calls the 
Control Manager function TrackControl . If the mouse button is released 
inside the control and the control is enabled, DialogSelect returns 
TRUE; otherwise, it returns FALSE. 

If the mouse button is pressed in any other enabled item, DialogSelect 
returns TRUE. If it's pressed in any other disabled item or in no 
item, or if any other event occurs, DialogSelect returns FALSE. 


PROCEDURE Modal Dialog (filterProc: ProcPtr; VAR itemHit: INTEGER); 

Call ModalDtalog after creating a modal dialog and bringing up its 
window in the frontmost plane. ModalDlalog repeatedly gets and handles 
events in the dialog’s window; after handling an event involving an 
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enabled dialog item, it returns with the item number in itemHit. 
Normally you* 11 then do whatever is appropriate as a response to an 
event in that item. 

ModalDialog gets each event by calling the Toolbox Event Manager 
function GetNextEvent . If the event is a mouse down event outside the 
content region of the dialog window, ModalDialog emits sound number 1 
(which should be a single beep) and gets the next event; otherwise, it 
filters and handles the event as described below. 

(hand) 

Once before getting each event, ModalDialog calls 
SystemTask, a Desk Manager procedure that needs to be 
called regularly if the application is to support the use 
of desk accessories. 

The filterProc parameter determines how events are filtered. If it's 
NIL, the standard filterProc is executed; this causes ModalDialog to 
return 1 in itemHit if the Return key or Enter key is pressed. If 
filterProc isn't NIL, ModalDialog filters events by executing the 
function it points to. The filterProc should have three parameters and 
should return a boolean value. For example, this is how it would be 
declared if it were named MyFilter: 

FUNCTION MyFilter (theDialog: DialogPtr; VAR theEvent: 

EventRecord; VAR item: itemHit) : BOOLEAN; 

A function result of FALSE tells ModalDialog to go ahead and handle the 
event, which either can be sent through unchanged or can be changed to 
simulate a different event. A function result of TRUE tells 
ModalDialog to return immediately rather than handle the event; in this 
case, the filterProc sets itemHit to the item number that ModalDialog 
should return. 

You can use the filterProc, for example, to treat a typed character in 
a special way (such as ignore it, or make it have the same effect as 
another character or as clicking a button); in this case, the 
filterProc would test for a key down event with that character. If you 
want it to be consistent with the standard filterProc, your filterProc 
should at least check whether the Return key or Enter key was pressed 
and, if so, return I in itemHit and a function result of TRUE. 

As another example, suppose the dialog box contains a user Item whose 
procedure draws a clock with the current time displayed. The 
filterProc can call that procedure and return FALSE without altering 
the current event. 

ModalDialog handles the events returned by the filterProc as follows: 

- If the mouse button is pressed in an editText item, ModalDialog 
responds to the mouse activity as appropriate (displaying an 
insertion point or selecting text). If a key down event occurs 
and there’s an editText item, text entry and editing are handled 
in the standard way for such items. In either case, ModalDialog 
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returns TRUE if the item is enabled or FALSE if it's disabled. If 
a key down event occurs when there’s no editText item, ModalDialog 
does nothing. 

- If the mouse button is pressed in a control, ModalDialog calls the 
Control Manager function TrackControl . If the mouse button is 
released inside the control and the control is enabled, 

ModalDialog returns; otherwise, it does nothing. 

- If the mouse button is pressed in any other enabled item in the 
dialog box, ModalDialog returns. If the mouse button is pressed 
in any other disabled item or in no item, or if any other event 
occurs, ModalDialog does nothing. 


PROCEDURE DrawDialog (theDialog: DialogPtr); 

DrawDialog draws the contents of the given dialog box. Since 
DialogSelect and ModalDialog handle dialog window updating, this 
procedure is useful only in unusual situations. 


Invoking Alerts 


FUNCTION Alert (alertID: INTEGER; filterProc: ProcPtr) : INTEGER; 

This function invokes the alert defined by the alert template that has 
the given resource ID. It calls the current sound procedure, if any, 
passing it the sound number specified in the alert template for this 
stage of the alert. If no alert box is to be drawn at this stage, 

Alert returns a function result of -l; otherwise, it creates and 
displays the alert window for this alert and draws the alert box. 

(hand) 

It creates the alert window by calling NewDialog, and 
does the rest of its processing by calling ModalDialog. 

Alert repeatedly gets and handles events in the alert window until an 
enabled item is clicked, at which time it returns the item number. 
Normally you’ll then do whatever is appropriate in response to a click 
of that item. 

Alert gets each event by calling the Toolbox Event Manager function 
GetNextEvent . If the event is a mouse down event outside the content 
region of the alert window, Alert emits sound number l (which should be 
a single beep) and gets the next event; otherwise, it filters and 
handles the event as described below. 

The filterProc parameter has the same meaning as in ModalDialog (see 
above). If it’s NIL, the standard filterProc is executed, which makes 
the Return key or the Enter key have the same effect as clicking the 
default button. If you specify your own filterProc and want to retain 
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chis feature, you must include it in your filterProc. You can find out 
what the current default button is by looking at the aDefltem field of 
the dialog record for the alert (via the dialog pointer passed to the 
filterProc) • 

Alert handles the events returned by the filterProc as follows: 

- If the mouse button is pressed in a control, Alert calls the 
Control Manager procedure TrackControl . If the mouse button is 
released inside the control and the control is enabled, Alert 
returns; otherwise, it does nothing. 

- If the mouse button is pressed in any other enabled item, Alert 
simply returns. If it f s pressed in any other disabled item or in 
no item, or if any other event occurs, Alert does nothing. 

Before returning to the application with the item number. Alert removes 
the alert box from the screen. (It disposes of the alert window and 
its associated data structures, the item list, and the items.) 

( hand ) 

The Alert function’s removal of the alert box would not 
be the desired result if the user clicked a check box or 
radio button; however, normally alerts contain only 
static text, icons, pictures, and buttons that are 
supposed to make the alert box go away. If your alert 
contains other items besides these, consider whether it 
might be more appropriate as a dialog. 


FUNCTION StopAlert (alertID: INTEGER; filterProc: ProcPtr) : INTEGER; 

StopAlert is the same as the Alert function (above) except that before 
drawing the items of the alert in the alert box, it draws the Stop icon 
in the top left corner of the box (within the rectangle (10,20,42,52)). 
The Stop icon is the icon having the resource ID 0. If the 
application’s resource file doesn’t include an icon with that ID 
number, the standard Stop icon in the system resource file is used. 


FUNCTION NoteAiert (alertID: INTEGER; filterProc: ProcPtr) : INTEGER; 

NoteAlert is the s^ne as the Alert function (above) except that before 
drawing the items of the alert in the alert box, it draws the Note icon 
in the top left corner of the box (within the rectangle (10,20,42,52)). 
The Note icon is the icon having the resource ID 1 « If the 
application’s resource file doesn’t include an icon with that ID 
number, the standard Note icon in the system resource file is used. 


FUNCTION CautionAlert (alertID: INTEGER; filterProc: ProcPtr) : 
INTEGER; 
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CautionAlert is the same as the Alert function (above) except that 
before drawing the items of the alert in the alert box, it draws the 
Caution icon in the top left corner of the box (Within the rectangle 
(10,20,42,52))* The Caution icon is the icon having the resource ID 2. 
If the application’s resource file doesn’t include an icon with that ID 
number, the standard Caution icon in the system resource file is used. 

PROCEDURE CouldAlert (alertID: INTEGER); 

CouldAlert ensures that the alert template having the given resource ID 
is in memory and makes it unable to be purged* It does the same for 
the alert window’s definition function, the alert’s item list, and any 
items defined as resources. This is useful if the alert may occur when 
the resource file isn’t accessible, such as during a disk copy* 


PROCEDURE FreeAlert (alertID: INTEGER); 

Given the resource ID of an alert template previously specified in a 
call to CouldAlert (above), FreeAlert undoes the effect of CouldAlert* 
It should be called when there’s no longer a need to keep the resources 
in memory. 


Manipulating Items in Dialogs and Alerts 


PROCEDURE ParamText ( param0 ,parami , param2 ,param3 : Str255 ) ; 

ParamText provides a means of substituting text in statText items: 
param0 through param3 will replace the special strings * , ~0” through 
in all statText items in all subsequent dialog or alert boxes. 
Pass empty strings for parameters not used* 


Assembly-language note : Assembly-language programmers may pass 
NIL for parameters not used or for strings that are not to be 
changed. 


For example, if the text is defined as ’’Cannot opep document "0” and 
docName is a string variable containing a document; name that the user 
typed, you can call ParamText (docName f ’) * 

(eye) 

All strings that will need to be translated to foreign 
languages should be stored in resource files. 
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Assembly-language note : The Dialog Manager stores handles to 
the four ParamText parameters in a system global array named 
daStrings. 


PROCEDURE GetDItem (the Dialog: DialogPtr; itemNo: INTEGER; VAR type: 
INTEGER; VAR item: Handle; VAR box: Rect); 

GetDItem returns in its VAR parameters the following information about 
the item numbered itemNo in the given dialog's item list: in the type 
parameter, the item type; in the item parameter, a handle to the item 
(or, for item type userltem, the procedure pointer); and in the box 
parameter, the display rectangle for the item. 

Suppose, for example, that you want to change the title of a control in 
a dialog box. You can get the item handle with GetDItem, convert it to 
a control handle, and call the Control Manager procedure SetCTitle to 
change the title. 

(hand) 

To access the text of a statText or editText item, pass 
the handle returned by GetDItem to GetIText or SetIText 
(see below). 


PROCEDURE SetDItera (theDialog: DialogPtr; itemNo: INTEGER; type: 
INTEGER; item: Handle; box: Rect); 

SetDItem sets the item numbered itemNo in the given dialog s item list, 
as specified by the parameters (without drawing the item). The type 
parameter is the item type; the item parameter is a handle to the item 
(or, for item type userltem, the procedure pointer); and the box 
parameter is the display rectangle for the item. 

Consider, for example, how to install an item of type userltem in a 
dialog: In the item list in the resource file, define an item in which 
the type is set to userltem and everything else is set to 0. Specify 
that the dialog window be invisible (in either the dialog template or 
the NewDialog call). After creating the dialog, convert the item's 
procedure pointer to a handle; then call SetDItem, passing that handle 
and the display rectangle for the item. Finally, call the Window 
Manager procedure ShowWindow to display the dialog window. 

( hand ) 

Do not use SetDItera to change the text of a statText or 
editText item; call GetDItem to get a handle to the item 
and then call SetIText (see below). 
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PROCEDURE GetIText (item: Handle; VAR text: Str255); 

Given a handle to a statText or editText item in a dialog box, as 
returned by GetDItem, GetXText returns the text of the item in the text 
parameter. 


PROCEDURE SetIText (item: Handle; text 2 Str255); 

Given a handle to a statText or editText item in a dialog box, as 
returned by GetDItem, SetIText sets the text of the item to the 
specified text and draws the item. For example , suppose the exact 
content of a dialog’s text item cannot be determined until the 
application Is running, but the display rectangle is defined in the 
resource file: Call GetDItem to get a handle to the item, and call 
SetIText with the desired text. 


PROCEDURE SellText (theDialog: DialogPtr; itemNo: INTEGER; 
scrtSel ,endSel: INTEGER); 

Given a pointer to a dialog and the item number of an editText item in 
the dialog box, SellText does the following: 

- If the item contains text, SellText sets the selection range to 
extend from character position strtSel up to but not including 
character position endSel* The selection range is inversely 
highlighted unless strtSel equals endSel, In which case a blinking 
vertical bar is displayed to indicate an Insertion point at that 
position. 

- If the item doesn’t contain text, SellText simply displays the 
insertion point. 

For example, if the user makes an unacceptable entry in the editText 
item, the application can put up an alert box reporting the problem and 
then select the entire text of the item so it can be replaced by a new 
entry. (Without this procedure, the user would have to select the item 
by dragging with the mouse before making the new entry.) 

(hand) 

You can select the entire text by specifying 0 for 
strtSel and a very large number for endSel. For details 
about selection range and character position, see the 
TextEdit manual or the CoreEdit manual. 


MODIFYING TEMPLATES IN MEMORY 


When you call GetNewDialog or one of the routines that invokes an 
alert, the Dialog Manager calls the Resource Manager to read the dialog 
or alert template from the resource file and return a handle to it. If 
the template is already in memory, the Resource Manager just returns a 
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handle to it* If you want, you can call the Resource Manager yourself 
to read the template into memory (and make it unpurgeable) , and then 
make changes to it before calling the dialog or alert routine* When 
called by the Dialog Manager, the Resource Manager will return a handle 
to the template as you modified it. 

To modify a template in memory, you need to know its exact structure 
and the data type of the handle through which it may be accessed* 

These are discussed below for dialogs and alerts. 


Dialog Templates in Memory 


data structure of a dialog template is 

as folio* 

TYPE DialogTemplate ■ RECORD 


bound s Rec t : 

Rect ; 

procID: 

INTEGER; 

visible : 

BOOLEAN ; 

fillerl: 

BOOLEAN; 

goAwayFlag : 

BOOLEAN; 

filler2 : 

BOOLEAN; 

refCon: 

Longlnt ; 

items ID: 

INTEGER; 

title : 

Str255 

END; 



The fiLlerl and filler2 fields are not used; they’re there only to 
ensure that the goAwayFlag and refCon fields begin on a wocd boundary* 
The itemsID field contains the resource ID of the dialog’s item list* 
The other fields are the same as the parameters of the same name in the 
NewDialog function* 

You access the dialog template by converting the handle returned by the 
Resource Manager to a template handle. 

TYPE DialogTPtr * "DialogTemplate ; 

DialogTHndl * "DialogTPtr; 

For example, if dHandle is a variable of type DialogTHndl, you can do 
the following: 

dHandle POINTER( ORD( Get Re source ( ’ DLOG ’ ,3 ) ) ) ; 
dHandle .visible :=* FALSE 

The Resource Manager function GetResource takes the resource type and 
resource ID as parameters and returns a handle to the resource* You 
use ORD and POINTER to make it have the data type DialogTHndl. 
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Alert. Templates in Memory 


The data structure of an alert template is as follows: 

TYPE AlertTemplate - RECORD 

boundsRect: Rect; 
items ID: INTEGER; 

stages: StageList 

END; 

BoundsRect is the rectangle that becomes the portRect of the window's 
graf Port . The itemsID field contains the resource ID of the item list 
for the alert* 

The information in the stages field determines exactly what should 
happen at each stage of the alert. It's packed into a word that has 
the following structure: 

TYPE StageList - PACKED ARRAY [1..4] OF. RECORD 

boldltera: 0..i; 
boxDrawn: BOOLEAN; 

sound: 0..3 

END; 

The elements of the StageList array are stored in reverse order of the 
stages: element 1 is for the fourth stage,, and element 4 is for the 
first stage. 

Boldltem indicates which button should be the default button (and 
therefore boldly outlined in the alert box). If the first two items in 
the alert's item list are* the OK button and the Cancel button, 
respectively, 0 will refer to the OK button and 1 to the Cancel button. 
The reason for this is that the value of boldltem plus 1 is interpreted 
as an item number, and normally items 1 and 2 are the OK and Cancel 
buttons, respectively. Whatever the item having the corresponding item 
number happens to be , a bold rounded~corner rectangle will be drawn 
around its display rectangle. 

(eye) r 

When deciding where to place items in an alert box, be 
sure to allow room for any bold outlines that may be 
d rawn « 

BoxDrawn is TRUE if the alert box is to be drawn. 

The sound field specifies which sound should be emitted at this stage 
of the alert, with a number from 0 to 3 that's passed to the current 
sound procedure. You can call ErrorSound to specify your own sound 
procedure; if you don't, sound number 0 will represent no sound, and 
sound numbers i through 3 will be the corresponding number of short 
beeps . 
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You access the alert template by converting the handle returned by the 
Resource Manager to a template handle. 

TYPE AlertTPtr = 'AlertTemplate ; 

AlertTHndl - 'AlertTPtr; 

For example, if aHandle is a variable of type AlertTHndl, you can do 
the following: 

aHandle POINTER(ORD(GetResource( ' ALRT ' , 1 ) ) ) ; 

aHandle". boxHeight 5 9 


As sembly-language note : Rather than offsets into the fields of 
the StageList data structure, the Toolbox equates file contains 
masks for accessing the information stored for an alert stage in 
a stages word. It also contains the system globals aNumber and 
aCount, which provide information about the last occurrence of 
an alert: its resource ID and its stage (as a number from 9 to 
3). 


FORMATS OF RESOURCES FOR DIALOGS AND ALERTS 

Every dialog template, alert template, and item list must be stored in 
a resource file, as must any icons or QuickDraw pictures in item lists 
and any control templates for items of type ctrlltem+resCtrl. The 
exact formats of a dialog template, alert template, and item list in a 
resource file are given below. For icons and pictures, the resource 
type is 'ICON' or 'PICT' and the resource data is simply the icon or 
the picture. The format of a control template is discussed in the 
Control Manager manual. 


Dialog Templates in a Resource File — 

The resource type for a dialog template is 1 DLOG ' , and the resource 
data has the same format as a dialog template in memory. 
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Number of bytes 
8 bytes 
2 bytes 
1 byte 
1 byte 
1 byte 

1 byte 
4 bytes 

2 bytes 
a bytes 


Contents 

Same as boundsRect parameter to NewDialog 
Same as procID parameter to NewDialog 
Same as visible parameter to NewDialog 
Ignored 

Same as goAwayFlag parameter to NewDialog 
Ignored 

Same as refCon parameter to NewDialog 
Resource ID of item list 
Same as title parameter to NewDialog 
(1-byte length in bytes, followed by 
the characters of the title) 


Alert Templates in a Resource File 


The resource type for an alert template is 1 ALRT 1 , and the resource 
data has the same format as an alert template in memory. 

Contents 

Rectangle enclosing alert window 
Resource ID of item list 
Stages 

The resource data ends with a word of information about stages. As 
illustrated In Figure 6, there are four bits of stage information for 
each of the four stages, from the four low— order bits for the first 
stage to the four high-order bits for the fourth stage. Each set of 
four bits is as follows: 


Number of bytes 
8 bytes 
2 bytes 
2 bytes 


Number of bits 
1 bit 

1 bit 

2 bits 


Contents 

Item number minus 1 of default button; 
normally 0 is OK and l is Cancel 
I if alert box is to be drawn; 0 if not 
Sound number (0 through 3) 
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4th stage 3rd stage 2nd stage 1st stage 

111111180111111101011 IQIOlOlOll- 


• — * — • 

sound 3 


1 v ' 

sound 3 

’ *- 

sound 2 

sound 1 

drw 
^ box 

* 

. drav 

U box 

_ no 
box 

— * no 
box 

outline 

outline 



— * Cancel 

* OK 




( value: hexadecimal F721) 

Figure 6* Sample Stages Word 


(hand) 

So that the disk won't be accessed just for an alert that 
beeps , you may want to set the resPreLoad attribute of 
the alert's template in the resource file- For more 
information, see the Resource Manager manual. 


Item Lists in a Resource File 

The resource type for an item list is 'DITL'- The resource data begins 
with a word containing the number of items in the list minus 1- This 
is what follows for each item: 


Number of bytes 
4 bytes 
8 bytes 
1 byte 
1 byte 
n bytes 
(n is even) 


Contents 

0 (placeholder for handle or procedure pointer) 
Display rectangle (local coordinates) 

Item type 

Length of following data in bytes 


If item type is: 
c. trlltem+resCtr 1 
any other ctrlltem 
statText , edicText 
iconltem, picltem 
userltera 


Content is: 

Resource ID (length 2) 
Title of the control 
The text 

Resource ID (length 2) 
Empty (length 0) 


As shown here, the first four bytes serve as a placeholder for the 
item's handle or, for item type userltem, its procedure pointer; the 
handle or pointer is stored after the item list is read into memory. 

The next eight bytes define the display rectangle for the item, and the 
next byte gives the length of the data that follows: for a text item, 
it's the text itself; for an icon, picture, or control of type 
ctrlltem+resCtrl , it *s the two-byte resource ID for the Item; and for 
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any ocher type of control, it's the title of the control. For 
userltems, no data follows the item type. When the data is text or a 
control title, the number of bytes it occupies must be even to ensure 
word alignment of the next item. 


Assembly-language note : The Toolbox equates file contains 
offsets into the fields of an item list. 
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SUMMARY OF THE DIALOG MANAGER 


Constants 


CONST Ctrl Item * 4; 

btnCtrl * 0; 

chkCtrl ■ 1; 

radCtrl ■ 2; 

resCtrl * 3; 

statText =* 8; 

editText * 16; 

iconltem * 32; 

picltem » 64; 

userltem » 0; 

itemDisable * 128; 

OK » 1; 

Cancel ■ 2; 


{add to following four constants} 
{standard button control} 

{standard check box control} 

{standard "radio button" control} 
{control defined in control template} 
{static text} 

{editable text (dialog only)} 

{icon} 

{QuickDraw picture} 

{application-defined item (dialog only)} 
{add to any of above to disable} 


Data Structures 


TYPE DialogPtr - WindowPtr; 

DialogPeek * "DialogRecord ; 

DialogRecord m RECORD 

window: WindowRecord ; 

items: Handle; 

textH: TEHandle; 

editField: INTEGER; 
editOpen: INTEGER; 

aDef Item: INTEGER 

END; 


DialogTHndl 

DialogTPtr 

DialogTemplate 


» "DialogTPtr; 

■ "DialogTemplate; 

■ RECORD 

bound sRect : 

Rect ; 

procID: 

INTEGER; 

visible : 

BOOLEAN; 

fillerl : 

BOOLEAN; 

go Away Flag : 

BOOLEAN; 

f iller2 : 

BOOLEAN ; 

ref Con : 

Long Inc ; 

1 terns ID: 

INTEGER; 

title : 

Str255 


END; 


AlertTHndl 

AlertTPtr 


“Aler tTPtr ; 
"AlertTemplate ; 
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AlertTemplate ■ RECORD 

boundsRecc: Rect; 
itemsID: INTEGER; 

stages: StageList 

END; 

StageUst - PACKED ARRAY [1..4] OF RECORD 

boldltein: 0..1; 
boxDrawn: BOOLEAN; 

sound : 0 . • 3 

END; 


Routines 


Initialization 

PROCEDURE InitDialogs ( restartProc : ProcPtr); 
PROCEDURE ErrorSound (soundPrOc: ProcPtr); 


Creating and Disposing of Dialogs 

FUNCTION NewDialog (dStorage: Ptr; boundsRect: Rect; title: Str255; 

visible: BOOLEAN; procID: INTEGER; behind: 
WindowPtr; goAwayFlag: BOOLEAN; ref Con: Longlnt; 
items: Handle) : DialogPtr; 

FUNCTION GetNewDialog (dialogID: INTEGER; dStorage: Ptr; behind: 

WindowPtr) : DiaiogPtr; 

PROCEDURE CloseDialog (the Dialog: DialogPtr); 

PROCEDURE DispcsDialog (theDialog: DialogPtr); 


Handling Dialog Events 


FUNCTION IsDlalogEvent (theEvent: EventRecord) : BOOLEAN; 

FUNCTION DialogSelect (theEvent: EventRecord; VAR theDialog: DialogPtr; 

VAR itemHit: INTEGER) : BOOLEAN; 

PROCEDURE ModalDialog (filterProc: ProcPtr; VAR itemHit: INTEGER); 

PROCEDURE DrawDialog (theDialog: DialogPtr); 


Invoking Alerts 

FUNCTION Alert (alertID: INTEGER; filterProc: ProcPtr) : INTEGER 

FUNCTION StopAlert (alertID: INTEGER; filterProc: ProcPtr) : INTEGER 

FUNCTION NoteAlert (alertID: INTEGER; filterProc: ProcPtr) : INTEGER 

FUNCTION CautionAlert (alertID: INTEGER; filterProc: ProcPtr) : INTEGER 

PROCEDURE CouldAlert (alertID: INTEGER); 

PROCEDURE FreeAlert (alertID: INTEGER); 
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Manipulating Items in Dialogs and Alerts 


PROCEDURE ParamText 
PROCEDURE GetDItem 

PROCEDURE SetDItem 

PROCEDURE Get IText 
PROCEDURE Set IText 
PROCEDURE Sel IText 


(param0 ,paraml ,param2 ,param3 : Str255 ) ; 

(theDialog: DialogPtr; itemNo: INTEGER; VAR type: 

INTEGER; VAR item: Handle; VAR box: Rect); 

( theDialog : DialogPtr ; itemNo: INTEGER; type: 

INTEGER; item: Handle; box: Rect); 

(item: Handle; VAR text: Str255); 

(Item: Handle; text: Str255); 

(theDialog: DialogPtr; itemNo: INTEGER; strtSel, 
end Sel : INTEGER); 


FllterProc for Modal Dialogs and Alerts 


FUNCTION My Filter (theDialog: DialogPtr; VAR theEvent: EventRecord; 

VAR item: ttemHit) : BOOLEAN; 


Assembly-Language Information 


Dialog Record Data Structure 


dWi ndow 

items 

teHandle 

editField 

editOpen 

aDef Item 


Dialog window' 

Resource ID of dialog’s item list 
Handle to editable text for TextEdit 
Item number minus 1 of editText item 
Used internally 
Item number of default button 


dWindLen Length of dialog record 


Dialog Template Data Structure 


d Bounds 

dWindProc 

dVisible 

dGoAway 

d Ref Con 

d Items 

dTitle 


Rectangle that becomes portRect of alert window’s grafPort 

Window definition ID 

Whether dialog window is visible 

Whether dialog window has a close box 

Dialog window’s reference value 

Resource ID of dialog’s item list 

Dialog window’s title 


Alert Template Data Structure 


a Bounds 
a Items 
aStages 


Rectangle that becomes portRect of dialog window’s grafPort 

Resource ID of alert's item list 

Stages word; information for alert stages 
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Item List Data Structure 


dlgMaxIndex 
i tmHndl 
i tmRect 
itmlype 
i tmData 


Number of items minus 1 

Handle or procedure pointer for this item 
Display rectangle for this item 
Item type for this item 

Length byte followed by that many bytes of 
data for this item (must be even length) 


Masks for Alert Stages Word 


volBits 

.EQU 

3 

; sound number 

alBit 

.EQU 

4 

;whether to draw box 

okDlstnis3al 

.EQU 

8 

;item number minus 1 of default button 


System Globals 


Name 

restProc 
daStrings 
daBeeper 
digFont 
a Number 
aCount ‘ 


Size 
4 bytes 
16 bytes 
4 bytes 
2 bytes 
2 bytes 
2 bytes 


Contents 

Address of restart fail-safe procedure 

Handles to ParamText strings 

Address of current sound procedure 

Font number for NewDialog 

Resource ID of last alert 

Stage number of last alert (0 through 3) 
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GLOSSARY 

alert: A warning or report of an error, in the form of an alert box, 

sound from the Macintosh's speaker, or both. 

alert box: A box that appears on the screen to give a warning or 
report an error during a Macintosh application. 

alert template: A resource that contains information from which the 
Dialog Manager can create an alert. 

alert window: The window in which an alert box is displayed. 

default button: In an alert box or modal dialog, the button whose 
effect will occur if the user presses the Return key or the Enter key. 

In an alert box,, it's boldly outlined; in a modal dialog, it's boldly 
outlined or the OK button. 

dialog: Same as dialog box. 

dialog box: A box that a Macintosh application displays to request 
information it needs to complete a command, or to report that it 3 
waiting for a process to complete. 

dialog record: The internal representation of a dialog, where the 
Dialog Manager stores all the information it needs for its operations 
on that dialog. 

dialog template: A resource that contains information from which the 
Dialog Manager can create a dialog. 

dialog window: The window in which a dialog box is displayed. 

disabled: A disabled item in a dialog or alert box has no effect when 

clicked . 

display rectangle: A rectangle that determines where an item is 
displayed within a dialog or alert box. 

icon: A 32-by-32 bit image that graphically represents an object, 

concept, or message. 

item: In dialog and alert boxes, a control, icon, picture, or piece of 

text, each displayed inside its own display rectangle. 

item list: A list of information about all the items in a dialog or 
alert box. 

item number: The index, starting from 1, of an item in an item list. 

modal dialog: A dialog that requires the user to respond before doing 
any other work on the desktop. 
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modeless dialog: A dialog that allows the user to work elsewhere on 
the desktop before responding. 

sound procedure: A procedure that will emit one of up to four sounds 
from the Macintosh's speaker. Its integer parameter ranges from 0 to 3 
and specifies which sound. 

stage: Every alert has four stages, corresponding to consecutive 
occurrences of the alert, and a different response may be specified for 
each stage. 
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COMMENTS? 

Macintosh User Education encourages your comments on this manual. 

- What do you like or dislike about it? 

- Were you able to find the information you needed? 

- Was it complete and accurate? 

- Do you have any suggestions for improvement? 

Please send your comments to the author (indicated on the coyer 
page) at 10460 Bandley Drive M/S 3-G, Cupertino CA 95014. 

Mark up a copy of the manual or note your remarks separately. 

(We'll return your marked-up copy if you like.) 

Thanks for your heipl 
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ABSTRACT 

The Macintosh Event Manager is your program's link to its human user, 
allowing it to monitor the user's actions with the mouse, keyboard, and 
keypad. A typical Macintosh application program is event-driven: it 
decides what to do from moment to moment by asking the Event Manager 
for events and responding to them one by one, in whatever way is 
appropriate. The Event Manager is also used for various purposes 
within the Toolbox itself, such as to coordinate the ordering and 
display of windows on the screen. Finally, you can use the Event 
Manager as a means of communication between parts of your own program. 
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ABOUT THIS MANUAL 


This manual describes the Event Manager, the part of the Macintosh User 
Interface Toolbox that allows your program to monitor the user's 
actions with the mouse, keyboard, and keypad. *** Eventually it will 
become part of a larger manual describing the entire Toolbox. *** The 
Event Manager is also used for various purposes within the Toolbox 
itself, such as to coordinate the ordering and display of windows on 
the screen. Finally, you can use the Event Manager as a means of 
communication between parts of your own program. 

(eye) 

This manual describes version 4 of the Macintosh ROM. If 
you're using a different version, the Event Manager may 
not work exactly as described here. 

Actually, there are two Event Managers: one in the Operating System 
and one in the Toolbox. The Toolbox Event Manager calls the one in the 
Operating System and serves as an interface between it and your 
application program; it also adds some features that aren't present at 
the Operating System level, such as the window management facilities 
mentioned above. This manual describes the Toolbox Event Manager, 
which is ordinarily the one your program will be dealing with. All 
references to "the Event Manager’* should be understood to refer to the 
Toolbox Event Manager. For information on the Operating System's Event 
Manager, see the Macintosh Operating System Reference Manual. 

Like all Toolbox documentation, this manual assumes you are familiar 
with the Macintosh User Interface Guidelines and with Lisa Pascal. You 
should also have at least a general notion of what the Window Manager, 
Desk Manager, Menu Manager, Control Manager, and Resource Manager do. 

It would also be helpful to have some familiarity with a Macintosh 
application program as an illustration of the concepts presented here. 

The manual begins with an introduction to the Event Manager and what 
you can do with it. It then discusses the various types of event, 
their relative priority., and how the user's keyboard actions, in 
particular, are reported in the form of events. Next come sections on 
the structure of event records, which contain all the pertinent 
information about each event, and event masks, which some of the Event 
Manager routines expect as parameters. 

A section on using the Event Manager introduces its routines and tells 
how they fit into the flow of your application program. This is 
followed by detailed descriptions of all Event Manager procedures and 
functions, their parameters, calling protocol, effects, side effects, 
and so on. 

Following these descriptions are sections that will not be of interest 
to all readers. Special information is given on the Event Manager's 
journaling mechanism, which allows your program's interactions with the 
user to be recorded and played back later; on the format used in 
resource files for storing a keyboard configuration, which determines 
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what character each key on the keyboard stands for; and on how to use 
the Event Manager routines from assembly language. 

Finally, there are an appendix containing detailed information on the 
standard Macintosh character set and keyboard configuration, a quick- 
reference summary of the Event Manager data structures and routines, 
and a glossary of terms used in this manual. 


ABOUT THE EVENT MANAGER . 

The Macintosh Event Manager is your program's link to its human user. 
Whenever the user presses the mouse button, types on the keyboard or^ 
keypad, or inserts a disk in a disk drive, your program is notified y 
means of an event. A typical Macintosh application progam is event- 
driven: it decides what to do from moment to moment by asking the 

Event Manager for events and responding to them one by one, in whatever 
way is appropriate. 

Although the Event Manager's primary purpose is to monitor the user s 
actions and pass them to your program in an orderly way, it also serves 
as a convenient mechanism for sending signals from one part of a 
program to another. For instance, the Window Manager uses events to 
coordinate the ordering and display of windows as the user activates 
and deactivates them and moves them around on the Macintosh screen. 

You can also define your own types of event and use them m any way 

your application calls for. 

Events waiting to be processed are kept in the even t queue. In 
principle, the event queue is a FIFO ( f irs t-in-f irst-out) list. events 
are added to the queue ( posted ) at one end and retrieved from the 
other. You can think of the queue as a funnel that collects events . 
from a variety of sources and feeds them to your program on demand, m 
the order they occurred. (There are a few exceptions to the strict 
FIFO ordering, which will be discussed later.) 


The event queue has a limited capacity *** (currently 30 
events, but may change) *** • When the queue becomes 
full, the Event Manager begins throwing out old events to 
make room for new ones as they're posted. The event 
thrown out is always the oldest one in the queue. 

Using the Event Manager, your program can: 

— Retrieve events one at a time from the event queue 

- Control which types of event get posted and which are ignored 


- Post events of its own 

- Read the current state of the keyboard, keypad, and mouse button 
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- Monitor the location of the mouse 

- Read the system clock to find out how much time has elapsed since 
the system was last started up 

Another important service provided by the Event Manager is journaling. 
This feature enables your program to record all its interactions with 
the Event Manager and play them back later. 


EVENT TYPES 


Events are of various types, depending on their origin and meaning. 

Some report actions by the user, some are generated by the Window 
Manager, some *** (not yet implemented) *** arise in the Macintosh's 
low-level input/output drivers, and some may be generated by your 
program itself for its own purposes. Some events are handled by the 
Desk Manager before your program ever sees them; others are left for 
your program to handle in its own way. 

The most important event types, the ones the Event Manager was created 
to handle, are those that record actions by the user: 

- Mouse down and mouse up events occur when the user presses or 
releases the mouse button. 

- Key down and key up events occur when the user presses or releases 
a key on the keyboard or keypad. The Event Manager also 
automatically generates auto-key events when the user presses and 
holds down a repeating key. Together, these three event types are 
called keyboard events . 

- Disk inserted events occur when the user inserts a disk into a 
disk drive. 

- Abort events occur when the user presses a special combination of 
keys. *** Tentatively the combination is Command-period 
(Command-.), but this may change; there's also some possibility 
that more than one key combination will be provided to interrupt a 
running program in different ways or for different purposes. *** 

An abort event signals the program to stop whatever it's doing and 
return control directly to the user, allowing the user to 
interrupt a time-consuming process or regain control of a runaway 
program. An abort event can also be generated by the Event 
Manager's own journaling mechanism, signaling the program to reset 
itself to some standard initial state before replaying a journal. 

(hand) 

Mere movements of the mouse are not reported as events. 

If necessary, your program can keep track of them by 
periodically asking the Event Manager for the current 
location of the mouse. 
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The following event types are used by the Window Manager to coordinate 
the display of windows on the screen: 

- Activate events are generated whenever an inactive window becomes 
active or vice versa. They generally occur in pairs (that is, one 
window is deactivated and another activated at the same time) • 

— Update events occur when a window's contents need to be redrawn, 
usually as a result of the user's opening, closing, activating, or 
moving a window. 

Two more event types (I/O driver events and network events ) are 
reserved for use by the low— level input/output system. *** At present, 
these types are not used at all. *** In addition, your program can 
define as many as four event types of its own and use them for whatever 
purposes you like. 

One final type of event is the null event , which is what the Event 
Manager returns if it has no other events to report. 


PRIORITY OF EVENTS — 

It was stated earlier that in principle the event queue is a FIFO list- 
that is, events are retrieved from the queue in the order they were 
originally posted. Actually, the way in which various types of event 
are generated and detected causes some to have higher priority than 
others. Furthermore, when you ask the Event Manager for an event, you 
can specify a particular type or types that are of interest. This can 
also alter the strict FIFO order, by causing some events to be passed 
over in favor of others that were actually posted later. Everything 
said in the following discussion is understood to be limited to the 
event types you've specifically requested in your Event Manager call. 

The Event Manager always returns the highest-priori ty event available 
of the requested type(s). The priority ranking is as follows: 

1. Activate (window becoming inactive before window becoming active) 

2. Mouse down, mouse up, key down, key up, disk inserted, abort, 
network, I/O driver, application-defined (all in FIFO order) 

3. Auto-key 

4. Update (in f ront-to-back order) 

5 . Null 

Activate events take priority over all others; they are detected in a 
special way, and are never actually placed in the event queue. The 
Event Manager checks for pending activate events before looking in the 
event queue, so it will always return such an event if one is 
available. Because of the special way activate events are detected, 
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there can never be more than two such events pending at the same time: 
one for a window becoming inactive and another for a window becoming 
active* If there s one of each, the event for the window becoming 
inactive is reported first. 

Category 2 includes most of the possible event types. Within this 
category, events are normally retrieved from the queue in the order 
they were posted. 

If no event is available in categories 1 and 2, the Event Manager next 
checks to see whether the appropriate conditions hold for an auto-key 
event. (These conditions are described in detail in the next section.) 
If so, it generates one and returns it to your program. 

Next in priority are update events. Like activate events, these are 
not placed in the event queue, but are detected in another way. If no 
higher-priority event is available, the Event Manager checks for 
windows whose contents need to be redrawn. If it finds one, it 
generates and returns an update event for that window. Windows are 
checked in the order in which they're displayed on the screen, from 
front to back, so if two or more windows need to be updated, an update 
event will be generated for the frontmost such window. 

Finally, if no other event is available, the Event Manager returns a 
null event. 


KEYBOARD EVENTS 


Every key on the Macintosh keyboard and the optional keypad generates 

key down and key up events when pressed and released. (Exceptions are 

the modifier keys — Shift, Caps Lock, Command *** name may change ***, 
and Option. These keys are treated specially, as described below, and 
generate no keyboard events of their own.) In addition, the Event 
Manager itself generates auto— key events whenever you request an event 
and all of the following conditions apply: 

- No higher-priority event of the requested type(s) is available 

- The user is currently holding down a key other than a modifier key 

- The appropriate time interval (see below) has elapsed since the 

last keyboard event 

- Auto-key events are one of the types you've requested 

- Auto-key events are one of the types currently being posted into 
the event queue 

Two different time intervals are taken into account. Auto-key events 
begin to be generated after a certain initial delay has elapsed since 
the original key down event (that is, since the key was originally 
pressed). Thereafter, they are generated each time a certain repeat 
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interval has elapsed since the last auto-key event. The initial 
settings for these two intervals are 16 ticks (sixtieths of a second) 
for the initial delay and 4 ticks for the repeat interval. The user 
can adjust these settings to individual preference with the control 
panel desk accessory. 

When the user presses, holds down, or releases a key, the resulting 
keyboard event identifies the key in two different ways: with a key 
code designating the key itself and a character code designating the 
character the key stands for. Character codes are given in the 
extended version of ASCII (the American Standard Code for Information 
Interchange) used by Macintosh and Lisa; see the Appendix for further 
information. 

The association between keys and characters is defined by a keyboard 
configuration . The particular character a key generates depends on 
three things: 

- The key itself 

- The keyboard configuration currently in effect 

- Which, if any, of the modifier keys were held down when the key 
was pressed 

As mentioned earlier, the modifier keys don't generate keyboard events 
of their own. Instead, they modify the meaning of the other keys by 
changing the character codes that those keys generate. For example, 
under the standard Macintosh keyboard configuration, the "C" key 
generates a lowercase letter c when pressed by itself; when pressed 
with the Shift or Caps Lock key down, it generates a capital C; with 
the Option key down, a lowercase c with a cedilla ( 9 ), used in French, 
Portuguese, and a few other foreign languages; and with Option and 
Shift or Option and Caps Lock down, a capital C with a cedilla (?)• 

The state of each of the option keys is also reported in a field of the 
event record (see next section) , where your program can examine it 
directly. 

Keyboard configurations are handled as resources and stored in resource 
files. The standard keyboard configuration gives each key its normal 
ASCII character code according to the standard Macintosh keyboard 
layout, as shown in the Appendix. When the Option key is held down, 
most keys generate special characters with codes between 128 and 255 
($80 and $FF) , included in the extended character set for business, 
scientific, and international use. 

(hand) 

Notice that under the standard keyboard configuration 
only the Shift, Caps Lock, and Option keys actually 
modify the character a key stands for: the Command key 
has no effect on the character code generated. (Keyboard 
configurations other than the standard may take the 
Command key into account.) Similarly, character codes 
for the keypad are affected only by the Shift key. To 
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find out whether the Command key was down at the time of 
an event (or Caps Lock or Option in the case of one 
generated from the keypad) , you have to examine the 
appropriate field of the event record. 

Normally you'll just want to use the standard keyboard configuration, 
which is read from the system resource file every time the Macintosh is 
started up. Other keyboard configurations can be used to reconfigure 
the keyboard for foreign use or for nonstandard layouts such as the 
Dvorak arrangement. In rare cases, you may want to define your own 
keyboard configuration to suit your program's special needs. For 
information on how to install an alternate keyboard configuration or 
define one of your own, see "Resource Format for Keyboard 
Configurations" and "Notes for Assembly-Language Programmers", below. 


EVENT RECORDS 


Every event is represented internally by an event record containing all 
pertinent information about that event. The event record includes the 
following information: 

- The type of event 

- The time the event was posted 

- The location of the mouse at the time the event was posted 

- The state of the mouse button and modifier keys at the time the 
event was posted 

- Any additional information required for a particular type of 
event, such as which key the user pressed or which window is being 
activated 

This information is filled into the event record for every event — even 
for null events, which just mean that nothing special has happened. 

Event records are defined as follows: 

TYPE EventRecord = RECORD 

what: INTEGER; 

message: Longlnt; 

when: Longlnt; 

where: Point; 

modifiers: INTEGER 

END; 

The what field contains an event code identifying the type of the 
event. The Event Manager can handle a maximum of 16 different event 
types, denoted by event codes from 0 to 15. The following standard 
event codes are built into the Event Manager as predefined constants: 
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CONST nullEvent = 0 


mouseDown 


1; 

mouseUp 

= 

2; 

keyDown 

= 

3; 

keyUp 

= 

4 ; 

autoKey 

= 

5; 

updateEvt 

= 

6; 

diskEvt 

= 

7; 

activateEvt 

= 

8; 

abortEvt 

= 

9; 

networkEvt 

= 

10 

driverEvt 

= 

11 

applEvt 


12 

app2Evt 

= 

13 

app3Evt 

= 

14 

app4Evt 

= 

15 


{null} 

{mouse down} 

{mouse up} 

{key down} 

{key up} 

{auto-key} 

{update} 

{disk inserted} 
{activate} 

{abort} 

{network} 

{ I/O driver} 

{application-defined} 

{application-defined} 

{application-defined} 

{application-defined} 


The when field contains the time the event was posted, in ticks 
(sixtieths of a second) since the system was last started up. 

The where field gives the location of the mouse at the time the event 
was posted, expressed in global coordinates. 


15 14 10 12 11 10 9 6 7 6 5 4 0 2 1 Q 



Figure 1. Modifier Bits 

The modifiers field gives the state of the mouse button ^ «:he 

modifier keys at the time the event was posted,- as shown below and in 

Figure 1. A 1 in any bit position means that that key or butto 
down; 0 means it was up. (Following the customary convention, the bit 

positions are numbered from right to left, starting from 0 at e o 

order end; see Figure !•) 
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Bit 

15-12 

11 

10 

9 

8 

7 

6-2 

1-0 


Meaning 
Unused 
Option key 
Caps Lock key 
Shift key 

Command key *** (name may change) *** 

Mouse button 

Unused 

Used only by activate events (see below) 


For activate events, the low-order bit of the modifiers field (bit 0) 
is set to 1 if a window is being activated, or to 0 if it is being 
deactivated. When one window is deactivated and another is activated 
at the same time (as is usually the case), bit 1 of the modifiers field 
is set to 1 if one of the windows involved belongs to your application 
program and the other is a system window (a window not created by your 
program, such as one containing a desk accessory); if they're both 
system or both application windows, this bit is set to 0. You can use 
this information to take some special action when the active window 
changes from an application window to a system window or vice versa: 
for example, you might want to hide a menu or dim some of its items 
when a system window becomes active and restore them when control 
returns to one of your program's own windows. 


31 24 23 16 15 8 7 0 



Character code 


Key code 


Figure 2. Event Message Format for Keyboard Events 

The message field contains the event message , which conveys extra 
information specific to a particular event type: 

- For keyboard events, the event message identifies the key that was 
pressed or released, as shown in Figure 2. The low-order byte 
(message MOD 256) contains the character code for the key, 
depending on the keyboard configuration currently in effect and on 
which, if any, of the modifier keys were held down. Under the 
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standard keyboard configuration this is just the normal ASCII code 
associated with the key, which is usually the information your 
program needs. The third byte (message DIV 256) gives the key 
code, useful in special cases (a music generator, for example) 
where you want to treat the keyboard as a set of buttons unrelated 
to specific characters. Detailed information on key and character 
codes for the standard Macintosh keyboard configuration is given 
in the Appendix. The first two bytes of the message are set to 0. 

- For disk inserted events, the event message gives the drive number 
of the disk drive: 1 for the Macintosh s built-in drive, 2 for 
the external drive, if any. Numbers greater than 2 denote 
additional disk drives connected through the serial port. By the 
time your program receives a disk inserted event, the system will 
already have attempted to mount the volume that was inserted. If 
for any reason the attempt was unsuccessful (for example, if the 
user has inserted an unformatted disk) , the high-order word of the 
event message will contain the error code returned by the 
Operating System; see the Operating System manual for further 
details. 

- For activate and update events, the event message is a pointer to 
the window affected. 

- For abort events, the event message identifies the key that the 
user pressed in order to interrupt the program. The format is the 
same as described above for keyboard events. For abort events 
generated by the Event Manager's own journaling mechanism, the 
message field is set to 0 . 


- For application-defined event types, you can use the event message 
for whatever information your application calls for. 

— For mouse down, mouse up, and null events, the event message is 
meaningless and should be ignored. 


EVENT MASKS 

Several of the Event Manager routines can be restricted to a specific 
event type or group of types. For instance, instead of just requesting 
the next available event, you can ask specifically for the next 
keyboard event . 

You specify which event types a particular Event Manager call applies 
to by supplying an event mask as a parameter. This is an integer in 
which each of the 16 bit positions stands for an event type, as shown 
in Figure 3. Notice that the bit position representing a given type 
corresponds to the event code for that type. For example, update 
events (type code 6) are specified by bit 6 of the mask, counting from 
0 at the right (low— order) end. A 1 bit at that position means that^ 
this Event Manager call applies to update events; a 0 means it doesn t. 
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15 14 13 12 11 IQ 3 8 7 6 5 4 3 2 1 0 



Null 

Mouse down 
Mouse up 
Key down 
Key up 
Auto-key 
Update 
Disk inserted 
Activate 
Abort 
Network 
I/O driver 

Application-defined 


Figure 3. Event Mask 


Masks for each single event type are 
predefined constants: 

CONST nullMask = 1; 


mDownMask 

= 

2; 

mUpMask 


4; 

keyDownMask 

= 

8; 

keyUpMask 

s 

16; 

autoKeyMask 

= 

32; 

updateMask 

= 

64; 

diskMask 


128; 

activMask 

= 

256; 

abortMask 

= 

512; 

networkMask 

= 

1024; 

driverMask 

= 

2048; 

applMask 

= 

4096; 

app2Mask. 


8192; 

app3Mask 

= 

16384; 

app4Mask 

* 

-32768 


built into the Event Manager as 


{null} 

{mouse down} 

{mouse up} 

{key down} 

{key up} 

{auto-key} 

{update} 

{disk inserted} 
{activate} 

{abort} 

{network} 

{I/O driver} 
{application-defined} 
{application-defined} 
{ applicat ion-def ined } 
{application-defined} 


There^s also a predefined mask consisting of all 1 bits, to designate 
every event type: 

CONST everyEvent = -1; 

You can form any mask you need by combining these mask constants with 
integer addition and subtraction. For example, to specify any keyboard 
event, you can use a mask of 

keyDownMask + keyUpMask + autoKeyMask 
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For any event except an update, you can use 
everyEvent - updateMask 


(hand) 

Recommended programming practice is always to use an 
event mask of everyEvent unless there is a specific 
reason not to. This ensures that all events will be 
processed in their natural order. 

In addition to the mask parameters to individual Event Manager 
routines, there's also a global system event mask , which controls which 
event types get posted into the event queue. Only those events 
corresponding to 1 bits in the system event mask are posted; those with 
0 bits are ignored. When the system is started up, the system event 
mask is initially set to post all except key up events — that is, it is 
initialized to 

everyEvent - keyUpMask 

(Key up events are meaningless for most applications, and your program 
will usually want to ignore them anyway.) If necessary for your 
particular application, you can change the setting of the system event 
mask with the Event Manager procedure SetEventMask. 


USING THE EVENT MANAGER 

This section discusses how the Event Manager routines fit into the 
general flow of your program and gives you an idea of which routines 
you'll need to use. The routines themselves are described in detail in 
the next section. 

Before using the Event Manager, you should call the Window Manager 
procedure InitWindows: parts of the Event Manager rely on the Window 
Manager's data structures and will not work properly unless those 
structures have been properly initialized. It's also usually a good 
idea to call F lushEvents( everyEvent ,0) , to empty the event queue of any 
stray events left over from before your program was started up (such as 
keystrokes typed to the Finder). 

As noted earlier, most application programs are event-driven. Such 
programs typically have a main loop that repeatedly calls GetNextEvent 
to retrieve the next available event, then uses a CASE statement to 
decide what type of event it is and take whatever action is 
appropriate. 

Your program is only expected to respond to those events that are 
directly related to its own operations. Events that are of interest 
only to the system, or that pertain only to system windows, are 
intercepted and handled by the Desk Manager, but are still reported 
back to your program by GetNextEvent. After calling GetNextEvent, you 
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should test its Boolean result to find out whether your program needs 
to respond to the event: TRUE means the event is of interest to your 
program, FALSE means you can ignore it. 

(hand) 

Events handled by the system include activate and update 
events for system windows; all keyboard and mouse up 
events when a system window is active, if the window 
contains a desk accessory that is prepared to handle the 
event; and network events if there's a desk accessory 
present that will handle them. Further details are given 
in the Desk Manager manual. 

On receiving a mouse down event, you should first call the Window 
Manager function FindWindow to find out where on the screen the mouse 
button was pressed; you can then respond in whatever way is 
appropriate. Depending on the part of the screen the button was 
pressed in, this may involve calls to Toolbox routines such as the Menu 
Manager function MenuSelect, the Desk Manager procedure SystemClick, 
the Window Manager routines SelectWindow, DragWindow, GrowWindow, and 
TrackGoAway, and the Control Manager routines FindControl, 

TrackControl, and DragControl. See the relevant Toolbox manuals for 
details . 

(hand) 

If your program attaches some special significance to 
double mouse clicks, you can detect them by comparing the 
time and location of each mouse down event with those of 
the previous such event. If the two events, are 
sufficiently close to each other in time and space — 
separated by not more than, say, half a second (30 ticks) 
and three pixels; — you can consider them a double click 
and respond accordingly. 

When one of your own windows is active, you should respond to keyboard 
and mouse up events in whatever way your application calls for. For 
example, when the user types a character on the keyboard, you might 
want to insert that character into the document displayed in an active 
document window. For keyboard events, you should first check the 
modifiers field to see whether the character was typed with the Command 
key held down: if so, the user may have been choosing a menu item by 
typing its keyboard equivalent. To find out, pass the character that 
was typed to the Menu Manager function MenuKey. If that character, 
combined with the Command key, stands for a menu item, MenuKey will 
return a nonzero result identifying the item. You can then do whatever 
is appropriate to respond to that menu item, just as if the user had 
chosen it with the mouse. If MenuKey' s result is 0, the user has typed 
a key combination that has no menu equivalent; your program may then 
want to respond in some other way. 

(hand) 

Under the Macintosh User Interface Guidelines, the 
keyboard's usual auto-repeat property doesn't apply to 
Command-key combinations that stand for menu items. When 
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you receive a nonzero result from MenuKey, you should 
execute the corresponding menu command only if the event 
you're responding to was a mouse down event; if it was an 
auto-key event, just ignore it and go on to the next 
event • 

When you receive an activate event for one of your own windows, the 
Window Manager will already have done all of the normal "housekeeping" 
associated with the event, such as highlighting or unhighlighting the 
window. You can then take any further action of your own that your 
application may require, such as showing or hiding a scroll bar or 
highlighting or unhighlighting a selection. 

On receiving an update event for one of your own windows, you should 
usually call the Window Manager procedure BeginUpdate, redraw the 
window's contents, then call EndUpdate. 

When you receive a disk inserted event, the Desk Manager will already 
have responded to the event by attempting to mount the new volume just 
inserted in the disk drive. Usually there's nothing more for your 
program to do, but GetNextEvent returns TRUE anyway, giving you an 
opportunity to take some further action if your application demands it. 
If the attempt to mount the volume was unsuccessful, there will be a 
nonzero error code in the high-order word of the event message; in this- 
case you might want to take some special action, such as displaying an 
alert box containing an error message. 

If the event you receive is an abort event, first check to see whether 
it was generated by the user or by the Event Manager's own journaling 
mechanism. For user-generated abort events, your program should stop 
whatever it's doing and return to its main loop to process the next 
available event; for those that originate in the journaling mechanism, 
it should reset its internal state as appropriate to prepare for 
replaying a journal. 

(hand) 

During any particularly time-consuming operation, your 
program should check for abort events periodically to 
allow the user to interrupt the operation from the 
keyboard. 

Network events are handled by the Desk Manager as long as there's a 
desk accessory present that can respond to them. If GetNextEvent 
returns a TRUE result for a network event, then no such desk accessory 
is present; your program should normally just ignore the event. 

*** The exact meaning and use of I/O driver events is not yet 
specified, so (for the time being) you needn't worry about how to 
respond to them. *** 

If you're using your own event types for internal communication between 
parts of your program, you can use PostEvent to post them into the 
event queue. When you receive them back from GetNextEvent, you can 
respond to them in whatever way is appropriate for your application. 
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To "peek" at pending events without removing them from the event queue 
use EventAvail instead of GetNextEvent . To remove all events of a 
given type or types from the queue, use FlushEvents. To control which 
event types get posted into the queue, or to cause certain types to be 
ignored, use SetEventMask. 


In addition to receiving the user's mouse and keyboard actions in the 
form of events, you can directly read the keyboard (and keypad), mouse 

and a jw?A n and state . of i ^e mouse button by calling GetKeys, GetMouse, 
•♦•v, u u’ res P ectlve ly • To follow the mouse when the user drags it 
with the button down, use StillDown or WaitMouseUp. 


Finally , you can read the current setting of the 
time by calling TickCount* 


system clock at any 


EVENT MANAGER ROUTINES 


This section describes all the Event Manager procedures and functions. 
They are presented in their Pascal form; for information on using them 
from assembiy language, see "Using the Toolbox from Assembly Language" 
(doesn t exist, but see QuickDraw manual) *** and also "Notes for 
Assembly-Language Programmers" in this manual. 


Accessing Events 


FUNCTION GetNextEvent (eventMask: INTEGER; VAR theEvent: EventRecord) • 
BOOLEAN; 


GetNextEvent returns the next available event of a specified type or 
types and removes it from the event queue. The event is returned as 
the value of the parameter theEvent; eventMask specifies which event 
types are of interest. GetNextEvent will return the next available 
event of any type designated by a I bit in the mask, subject to the 
priority rules discussed above under "Priority of Events". Event types 
corresponding to 0 bits in the mask are ignored. If no event of any of 
t e esignated types is available, GetNextEvent returns a null event 
regardless of the setting of the eventMask bit for null events. 


(eye) 

Since update events are never actually placed in the 
event queue, GetNextEvent can't remove them from the 
queue before returning them, as it does with other 
events. If your program doesn't take some explicit 
action to "clear" the update event, it will keep getting 
the same event back again. The normal way of clearing an 
update event is with BeginUpdate and EndUpdate; further 
explanation can be found in the Window Manager manual. 
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Before reporting an event to your program, GetNextEvent first calls the 
Desk Manager function SystemEvent to see whether the system wants to 
intercept and respond to the event* If so (or if the event being 
reported is a null event) , GetNextEvent returns a function result of 
FALSE to notify your program that it can ignore this event; a function 
result of TRUE means that your program should handle the event itself. 
The Desk Manager normally intercepts the following events: 

- All activate and update events directed to a system window 


- All keyboard and mouse up events if the currently active window is 
a system window and contains a desk accessory that is prepared to 
handle the event 

- All network events if there is a desk accessory -present that can 
handle them 

The Desk Manager also responds to disk inserted events by attempting to 
mount the volume that has just been inserted; but in this case 
GetNextEvent returns TRUE to allow your program to take some further 
action if appropriate. All other events (including all mouse down 
events, regardless of which window is active) are left for your program 
to handle. See the Desk Manager manual for further details. 


FUNCTION EventAvail (eventMask: INTEGER; VAR theEvent : EventRecord) : 
BOOLEAN; 

EventAvail returns in theEvent the next available event of the type or 
types specified by eventMask, but does not remove the event from the 
event queue. This allows you to "peek" at pending everits while still 
leaving them in the queue for later processing. In all other respects, 
EventAvail works exactly the same as GetNextEvent (see above). 


Posting and Removing Events 


PROCEDURE PostEvent (eventCode: INTEGER; eventMsg: Longlnt); 

PostEvent places in the event queue an event of the type designated by 
eventCode, with the event message specified by eventMsg. The main use 
of this procedure is for posting events of your own application-defined 
types. It's also sometimes useful for placing an event back in the 
queue after you've removed it with GetNextEvent. Notice, however, that 
in this case the system clock time, mouse location, and state of the 
mouse button and modifier keys will be changed from their original 
values to those in effect at the time the event is reposted. 

(eye) 

Be very careful about posting any but your own 
application— def ined events into the queue. For example, 
attempting to post an activate or update event will 
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interfere with the internal operation of the Event 
Manager, since such events are detected in other ways and 
are not normally placed in the queue at all. If you 
repost a mouse event, the mouse location associated with 
it will be changed, possibly altering its meaning; 
reposting a keyboard event may cause modifier information 
to be lost or characters to be transposed from the order 
in which the user originally typed them. In general, you 
should avoid using PostEvent for any but your own events 
unless you're sure you know what you" re doing. 

PROCEDURE FlushEvents ( eventMask, stopMask: INTEGER) ; 

FlushEvents removes from the event queue all events of the type(s) 
specified by eventMask, up to, but not including, the first event of 
any type specified by stopMask. To remove all events of a particular 
type or types, use a stopMask value of 0. You might use FlushEvents, 
for example, on receiving an abort event, to remove any mouse or 
keyboard events that may have occurred before the program was 
interrupted. 

(hand) 

When your program is first started up, it's usually a 
good idea to call FlushEvents(everyEvent ,0) to empty the 
event queue of any stray events that may have been left 
lying around, such as unprocessed keystrokes typed to the 
Finder. 


Reading the Mouse 


PROCEDURE GetMouse (VAR mouseLoc: Point); 

GetMouse returns the current mouse location as the value of the 
parameter mouseLoc. The location is expressed in the local coordinate 
system of the current grafPort (which might be, for example, the 
currently active window) • Notice that this differs from the mouse 
location stored in the where field of an event record, which is given 
in global coordinates. 


FUNCTION Button : BOOLEAN; 

The Button function returns the current state of the mouse • button: 
TRUE if the button is down, FALSE if it isn't. 


FUNCTION StillDown : BOOLEAN; 

Called after a mouse down event, StillDown tests whether the mouse 
button is still down. It returns TRUE if the button is currently down 
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and there are no more mouse events (mouse ups or later mouse downs) 
pending in the event queue. This is a true test of whether the button 
is still down from the original press — unlike Button (see above) , which 
returns TRUE whenever the button is currently down, even if it has been 
released and pressed again since the original mouse down event. 


FUNCTION WaitMouseUp : BOOLEAN; 

WaitMouseUp works exactly the same as StillDown (see above), except 
that if the button is not still down from the original press, 
WaitMouseUp removes the corresponding mouse up event before returning 
FALSE. 


Reading the Keyboard and Keypad 


PROCEDURE GetKeys (VAR theKeys: KeyMap) ; 

GetKeys reads the current state of the keyboard (and keypad, if any) 
and returns it in the form of a keyMap: 

TYPE KeyMap = PACKED ARRAY [1..128] OF BOOLEAN; 

Each element of the keyMap is TRUE if the corresponding key is down, 
FALSE if it isn't. The correspondence between elements of the keyMap 
and keys on the keyboard and keypad is shown in Table 1. KeyMap 
elements corresponding to blank entries in the. table are unused. 
Notice that GetKeys doesn't distinguish between the two Shift keys or 
the two Option keys. 
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Element Key Element 


0 

A 

48 

1 

S 

49 

2 

D 

50 

3 

F 

51 

4 

H 

52 

5 

G 

53 

6 

Z 

54 

7 

X 

55 

8 

c 

56 

9 

V 

57 

10 


58 

11 

B 

59 

12 

Q 

60 

13 

w 

61 

14 

E 

62 

15 

R 

63 

16 

Y 

64 

17 

T 

65 

18 

1 

66 

19 

2 

67 

20 

3 

68 

21 

4 

69 

22 

6 

70 

23 

5 

71 

24 

= 

72 

25 

9 

73 

26 

7 

74 

27 

- 

75 

28 

8 

76 

29 

0 

77 

30 

] 

78 

31 

0 

79 

32 

U 

80 

33 

[ 

81 

34 

I 

82 

35 

P 

83 

36 

Return 

84 

37 

L 

85 

38 

J 

86 

39 

* 

87 

40 

K 

88 

41 

y 

89 

42 

\ 

90 

43 

y 

91 

44 

/ 

92 

45 

N 

93 

46 

M 

94 

47 

• 

95 



96-127 


Key 

Tab 

Space bar 

Backspace 

Enter 


Command *** (name may change) 

Shift 

Caps Lock 

Option 


. (keypad) 
* (keypad) 


+ (keypad) 
Clear (keypad) 
, (keypad) 


Enter (keypad) 
/ (keypad) 

- (keypad) 


0 (keypad) 

1 (keypad) 

2 (keypad) 

3 (keypad) 

4 (keypad) 

5 (keypad) 

6 (keypad) 

7 (keypad) 

8 (keypad) 

9 (keypad) 


(Unused) 


Table 1. KeyMap Elements 
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Miscellaneous Utilities 


PROCEDURE SetEventMask (theMask: INTEGER); 

SetEventMask sets the system event mask to the specified value. This 
mask controls the posting of events into the event queue. Only event 
types corresponding to 1 bits in the mask are posted; all others are 
ignored. The initial setting for the system event mask is to post all 
except key up events. 

SetEventMask is useful if for some reason you want to know when keys 
are released as well as when they're pressed, or if you know that some 
other event type is of no interest to your program and needn t be 
posted. For example, if your program attaches no special meaning to 
mouse up events, you may want to dispense with them; or you might want 
to eliminate keyboard repeat by preventing auto-key events from being 
posted. 

(hand) 

Since space in the event queue is limited, it's generally 
a good idea to disable any event type that you know your 
program has no use for. 

The system event mask has no effect on activate or update events, since 
these events are detected in other ways and are never actually posted 
into the event queue. 


FUNCTION TickCount : Longlnt; 

TickCount returns the current value of the system clock, which gives 
the elapsed time in ticks (sixtieths of a second) since the system was 
last started up. 


JOURNALING 

Using the Event Manager's journaling mechanism, all of a program s 
interactions with the Event Manager can be recorded and later played 
back, just as if they were happening for the first time. A journal is 
a record of all calls to the Event Manager routines GetNextEvent , 
EventAvail, GetMouse, Button, GetKeys, and TickCount. When a journal 
is being recorded, every call to any of these routines is sent to a 
special input/output driver and recorded in the journal, along with the 
result returned. 

When the journal is played back, the same Event Manager calls read 
their results back from the journal instead of directly from the mouse, 
keyboard, keypad, and system clock. To the application program, the 
results it receives from the Event Manager in response to these calls 
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The primary aid to assembly-language programmers is a file named 
TOOLEQU • TEXT • If you use .INCLUDE to include this file when you 
assemble your program, all the Event Manager constants, offsets to 
locations of global variables, and offsets into fields of structured 
types will be available in symbolic form. 

In assembly language, you can control the operation of the journaling 
mechanism by setting the global variable JournalFlag. Setting this 
variable to a positive, nonzero value turns on journal recording; 
setting it negative turns on playback; setting it to 0 turns journaling 
off. 

The global variables KeylTrans and Key2Trans are used to hold pointers 
to the keyboard and keypad configuration routines, respectively. You 
can replace either or both of these routines "on the fly" by the 
following steps: 

1. Call the Resource Manager function GetResource (or 
GetNamedR.esource) to find the new configuration routine in its 
resource file, read it into memory, and get a handle to it. 

2. Use the Operating System call RecoverHandle to convert the 
existing routine pointer from KeylTrans or Key2Trans into a 
handle. 

3. Use the Operating System call DisposHandle to free the storage 
occupied by the old routine. 

4. Convert the handle you received from the Resource Manager into a 
pointer and store it in KeylTrans (for a keyboard routine) or 
Key2Trans (for a keypad routine). 


APPENDIX : STANDARD KEY AND CHARACTER CODES 

The following tables show the key and character codes used by Macintosh 
and the characters assigned to keys on the keyboard and keypad under 
the standard Macintosh keyboard configuration. All key and character 
codes are given in hexadecimal; for the benefit of readers with only 
ten fingers, there^s a hexadecimal/decimal conversion table at the end 
of this Appendix. 

Table 2 shows the extended ASCII character set used by Macintosh and 
Lisa. The first digit of the hexadecimal character code is shown at 
the top of the table, the second down the left side. For example, 
character code $47 stands for the capital letter G, which appears in 
the table at the intersection of column 4 and row 7 . 

Character codes between $20 and $7E have their normal ASCII meanings. 
Codes between $80 and $CA denote special characters included in the 
extended character set for business, scientific, and international use; 
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codes from $CB to $FF are unassigned. ASCII control characters ($00 to 
$1F, as well as $20 and $7F) are identified in the table by their 
traditional ASCII abbreviations: 


Code 

Abbr. 

Meaning 

Code 

Abbr. 

Meaning 

JW 

NUL 

Null 

$10 

DLE 

Data Link Escape 

$01 

SOH 

Start of Header 

$11 

DC1 

Device Control 1 

$02 

STX 

Start of Text 

$12 

DC2 

Device Control 2 

$03 

ETX 

End of Text 

$13 

DC3 

Device Control 3 

$04 

EOT 

End of Tape 

$i4 

DC4 

Device Control 4 

$05 

ENQ 

Enquiry 

$15 

NAK 

Negative Acknowledge 

$06 

ACK 

Acknowledge 

$16 

SYN 

Synchronous Idle 

$07 

BEL 

Bell 

$17 

ETB 

End Transmission Block 

$08 

BS 

Backspace 

$18 

CAN 

Cancel 

$09 

HT 

Horizontal Tab 

$19 

EM 

End of Medium 

$0A 

LF 

Line Feed 

$1A 

SUB 

Substitute 

$0B 

VT 

Vertical Tab 

$1B 

ESC 

Escape 

$0C 

FF 

Form Feed 

$1C 

FS 

Field Separator 

$0D 

CR 

Carriage Return 

$1D 

GS 

Group Separator 

$0E 

SO 

Shift Out 

$1E 

RS 

Record Separator 

$0F 

SI 

Shift In 

$1F 

US 

Unit Separator 

$20 

SP 

Space 

$7F 

DEL 

Delete 


However, most of these characters have no special meaning on Macintosh 
and cannot be generated from the Macintosh keyboard under the standard 
keyboard configuration. The exceptions are the following: 


Code 

Character 

Key 

$03“ 

ETX 

Enter (keyboard and keypad) 

$08 

BS 

Backspace 

$09 

HT 

Tab 

$0D 

CR 

Return 

$1B 

ESC 

Clear (keypad) 

$1C 

FS 

Left arrow (keypad) 

$ ID 

GS 

Right arrow (keypad) 

$ IE 

RS 

Up arrow (keypad) 

$ IF 

US 

Down arrow (keypad) 

$20 

SP 

Space bar 

addition. 

as shown in 

the table, codes from $11 to $15 denote 


special characters used on the Macintosh screen, such as the open and 
solid Apple characters. These characters are intended exclusively for 
use on the screen, and have no keyboard or keypad equivalents under the 
standard keyboard configuration. 

The characters shaded in the table are accented letters used in various 
foreign languages. Under the standard keyboard configuration, these 
characters cannot be typed directly from the keyboard. Instead, they 
are generated by first typing the accent or diacritical mark alone, 
followed by the letter to be accented. For example, a lowercase letter 
e with a grave accent (e, character code $8F) is produced by typing a 
grave accent (^, code $60) followed by a lowercase e (code $65). The 
Macintosh keyboard driver will *** (eventually) *** translate such two- 
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character sequences involving diacriticals into the corresponding 
single accented letters. 

Tables 3 and 4 show the hexadecimal key codes corresponding to keys on 
the Macintosh keyboard and keypad, respectively. Modifier keys are not 
shown, since they never generate keyboard events of their own. 

Table 5 shows the hexadecimal character codes generated by each key on 
the keyboard under the standard keyboard configuration. Table 5a gives 
the character generated when the key is pressed by itself, Table 5b 
when it is pressed with the Shift key held down, Table 5c the Caps Lock 
key, Table 5d the Option key, and Table 5e the Option and Shift or 
Option and Caps Lock keys. Again, the modifier keys themselves are not 
shown. 

Table 6 shows the hexadecimal character codes for the keypad under the 
standard keyboard configuration. Table 6a gives the character 
generated when the key is pressed by itself, Table 6b when it is 
pressed with the Shift key held down. 

Finally, Table 7 is a conversion table between hexadecimal and decimal. 
To convert a two-digit hexadecimal number to decimal, find its first 
digit at the top of the table and its second down the left side. The 
decimal equivalent is found at the intersection of that column and row. 
For example, hexadecimal $6C is equivalent to decimal 108, found at the 
intersection of column 6 and row C. To convert a decimal number to 
hexadecimal, find the number in the body of the table and read its 
first and second hexadecimal digits from the head of that column and 
row, respectively. For example, decimal 227 is in column E and row 3, 
so its hexadecimal equivalent is $E3 . 
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0 

1 

2 

3 

a 

5 

6 

7 

8 
9 
A 
B 
C 
D 
E 
F 


0 l 2 3 4 5 6 7 8 9ABCDE F 


NUL 

OLE 

SP 

0 

@ 

p 

% 

p! 

, ■% • . 

A 

■ A 

|;:e:; 

t 

OO 

• 

£ 



| 

SO H 

DCl 

6 

l 

• 

i 

A 

Q 

a 

q 

A 

*•*•«•* 

re:: 

o 

+ 

• 

1 



w. 

STX 

DC2 

V 

□ 





B 

fl 

1 

i 


< 




r:i 

fl 

DC3 

♦ 

# 

3 

C 

S 

c 

s 

E': 

In.: 

£ 

> 

4 




EOT 

DC4 

♦ 

$ 

4 

D 

T 

d 

t 

ft 


:>*. • 

i 

§ 

¥ 

f 



r;s 

ENO 

NAK 

* 

% 

5 

E 




fl 

1 


• 

M- 

~ 

B 

B 

flj 


SYN 

8c 

6 

F 

V 

f 



1 




B 

fl 

B 

fl] 

BEL 

ETB 

■ 

fl 



fl 



j 

B 




B 

B 

fl 

BS 

CAN 

n 




h 

X 

a 

r 

d 


TT 





m 

Efl 

) 

9 

i 

n 

B 

n 


l 



7T 

B 

B 

B 

fl 

a 

SU8 

D 

■ 

H 

z 

B 





B 

fl 

fl 

B 

» 

VT 

ESC 

CS3 

+ 

■ 

K 

n 

H 

n 


|P 

B 

a 




T 

■ 

FS 

3=) 

■ 

H 

L 

n 

1 

i 

o 

a 

i ur 


o 





fl 

GS 

(=5 

B 

= 

M 

n 


> 

H 



Q 




4- 

SO 

RS 

GA] 

■ 

B 

N 

B 

n 

B 


19 

D 

/E 

ae 

B 

fl 

■ 

■ 

SI 

US 

cri 

/ 

■ 

o 

B 

o 

OEL 


fl 

0 

H 

B 

B 

■ 

fl 





4 ^ — W 


Non-printing Printing characters 


Table 2. Macintosh and Lisa Extended ASCII Character Set 
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Key: 

Code: 

Key: 

Code: 

Key: 

Code: 

Key: 

Code: 

Key: 

Code: 
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P] [1] [2] [3] [4] [5] [6] [7] [8] [9] [0] [-] [=] [Backspace] 

$32 $12 $13 $14 $15 $17 $16 $1A $1C $19 $1D $1B $18 $33 

[Tab] [Q] [W] [E] [R] [T] [Y] [U] [I] [0] [P] [[] []] [\] 

$30 $0C $0D $0E $0F $11 $10 $20 $22 $1F $23 $21 $1E $2A 

[A] [S] [D] [F] [G] [H] [J] [K] [L] [;] ['] [Return] 

$00 $01 $02 $03 $05 $04 $26 $28 $25 $29 $27 $24 

[Z] [X] [C] [V] [B] [N] [M] [,] [.] [/] 

$06 $07 $08 $09 $0B $2D $2E $2B $2F $2C 

[ Space ] [ Enter ] 

$31 $34 


Table 3. Key Codes for Macintosh Keyboard 


Key: 

[Clear] 

[-] 

[+] 

[*] 

Code: 

$47 

$4E 

$46 

$42 

Key: 

[7] 

[8] 

[9] 

[/] 

Code: 

$59 

$5B 

$5C 

$4D 

Key: 

[M 

[5] 

[6] 

[,] 

Code: 

$56 

$57 

$58 

$48 

Key: 

[1] 

[2] 

[3] 

[E] 

Code: 

$53 

$54 

$55 

[n] 





[t] 





[e] 

Key: 

[ ' 

0 ] 

[•] 

[r] 

Code: 

$52 

$41 

$4C 


Table 4. Key Codes for Macintosh Keypad 
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Key: 

Code: 

Char: 

Key: 

Code: 

Char: 

Key: 
Code: 
Char : 

Key: 

Code: 

Char: 

Key: 
Code: 
Char : 


['] [1] [2] [3] [4] [5] [6] [7] [8] [9] [0] [-] [=] [Backspace] 
$60 $31 $32 $33 $34 $35 $36 $37 $38 $39 $30 $2D $3D $08 

1234567890-= BS 


[Tab] [Q] [W] [E] [R] [T] [Y] [U] [I] [0] [P] [[] []] [\] 

$09 $71 $77 $65 $72 $74 $79 $75 $69 $6F $70 $5B $5D $5C 

HT qwe r t yu i.o p [ ] \ 


[A] [S] [D] [F] [G] [H] [J] [K] [L] [;] ['] [Return] 
$61 $73 $64 $66 $67 $68 $6A $6B $6C $3B $27 $0D 

asdfghjkl;' CR 

[Z] [X] [C] [V] [B] [N] [M] [,] [.] [/] 

$7A $78 $63 $76 $62 $6E $6D $2C $2E $2F 
zxcvbnm,./ 


[ 


Space 

$20 

SP 


[ Enter ] 

$03 

ETX 


(a) Unshifted 


Table 5. Standard Character Codes for Macintosh Keyboard 
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Key: 

Code: 

Char: 

Key: 

Code: 

Char: 

Key: 

Code: 

Char: 

Key: 

Code: 

Char: 

Key: 

Code: 

Char: 


Key: 

Code: 

Char: 

Key: 

Code: 

Char: 

Key: 

Code: 

Char: 

Key: 

Code: 

Char: 

Key: 

Code: 

Char: 


Table 


['] [1] [2] [3] [4] [5] [6] [7] [8] [9] [0] [-] [=] [Backspace] 

$7E $21 $40 $23 $24 $25 $5E $26 $2A $28 $29 $5F $23 $08 

!@ #$%“&*()_+ BS 

[Tab] [Q] [W] [E] [R] [T] [Y] [U] [I] [0] [P] [[] []] [\] 

$09 $51 $57 $45 $52 $54 $59 $55 $49 $4F $50 $7B $7D $7C 

HTQWERTYUI0P{ } | 

[A] [S] [D] [F] [G] [H] [J] [K] [L] [;] ['] [Return] 

$41 $53 $44 $46 $47 $48 $4A $4B $4C $3A $22 $0D 

ASDFGHJKL: CR 

[Z] [X] [C] [V] [B] [N] [M] [,] [.] [/] 

$5A $58 $43 $56 $42 $4E $4D $3C $3E $3F 

ZXCVBNM<> ? 

[ Space ] [ Enter ] 

$20 $03 

SP ETX 


(b) Shift Key Down 


['] [1] [2] [3] [4] [5] [6] [7] [8] [9] [0] [-] [=] [Backspace] 
$60 $31 $32 $33 $34 $35 $36 $37 $38 $39 $30 $2D $3D $08 

1234567890-= BS 


[Tab] [Q] [W] [E] [R] [T] [Y] [U] [I] [0] [P] [[] []] [\] 

$09 $51 $57 $45 $52 $54 $59 $55 $49 $4F $50 $5B $5D $5C 

HTQWERTYUIOP [ ] \ 

[A] [S] [D] [F] [G] [H] [J] [K] [L] [;] ['] [Return] 
$41 $53 $44 $46 $47 $48 $4A $4B $4C $3B $27 $0D 

ASDFGHJKL;' CR 

[Z] [X] [C] [V] [B] [N] [M] [,] [.] [/] 

$5A $58 $43 $56 $42 $4E $4D $2C $2E $2F 

ZXCVBNM , ./ 


Space 

$20 

SP 


] [ Enter ] 
$03 
ETX 


(c) Caps Lock Key Down 


5. Standard Character Codes for Macintosh Keyboard (continued) 
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Key: ['] [1] [2] [3] [4] [5] [6] [7] [8] [9] [0] [-] [ = ] [Backspace] 

Code: $60 $C1 $AA $A3 $A2 $B0 $A4 $A6 $A5 $BB $BC $Bl $AD $08 
Char: ' BS 


Key: 

Code: 

Char: 

Key: 

Code: 

Char: 

Key: 
Code: 
Char : 

Key: 
Code: 
Char : 


[Tab] [Q] [W] [E] [R] [T] [Y] [U] [I] [0] [P] [[] []] [\] 

$09 $A1 $B7 $AB $A8 $A0 $B4 $AC $00 $BF $B9 $B5 $C8 $00 

ht ° ^ ^ *’ 0 -tr /a 4c 

[A] [S] [D] [F] [G] [H] [J] [K] [L] [;] ['] [Return] 
$8C $ A7 $B6 $C4 $A9 $5E $C6 $00 $C2 $BD $BE $0D 

s b a / © • & n. « 

(Z) [X] [C] [V] IB] [N] [M] [,] [•] [/] 

$00 $C5 $8D $C3 $BA $7E $00 $B2 $B3 $C0 

9 J j ~ < > i 

[ Space ] [ Enter ] 

$20 $03 

SP ETX 


(d) Option Key Down 


Key: 

['] [1] [2] [3] [4] 

[5] [6] [7] [8] [9] [0] [-] [=] [Backspace] 

Code: 

$60 $C1 $AA $ A3 $A2 

$B0 $A4 $A6 $A5 $BB $BC $B1 $AD 

$08 

Char: 

' i w i 



o + t 

BS 

Key: 

[Tab] [Q] [W] 

[E] [R] [T] [Y] [U] [I] 

[0] [P] [[] []] 

[\] 

Code: 

$09 $A1 $B7 

$AB $A8 $A0 $B4 $AC $00 

$AF $B8 $B5 $C7 

$00 

Char : 

HT * <jT 

' ® t y •• 

* T M- » 


Key: 

[A] [£ 

5] [D] 

[F] [G] [H] [J] [K] [L] [;] ['] [Return] 

Code: 

$81 $A7 $B6 

$C4 $A9 $5E $C6 $00 $C2 $BD $AE 

$0D 

Char: 

* ? 

> 9 

f ® * A 

- SI FL 

CR 

Key: 

[Z] 

[X] [C] [V] [B] [N] [M] 

[,] [•] [/] 


Code: 

$00 

$C5 $82 $C3 $BA $7E $00 

$B2 $B3 $C0 


Char: 




< ^ i 


Key: 


l 

Space 

] [ Enter ] 


Code: 



$20 

$03 


Char: 



SP 

ETX 



(e) Option and Shift or Option and Caps Lock Keys Down 


Table 5. Standard Character Codes for Macintosh Keyboard (continued) 
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APPENDIX 

: STANDARD 

KEY 

AND CHARACTER CODES 

Key: 

[Clear] 

[-] 

[+] 

[*] 

Code: 

$1B 

$2D 

$1C 

$ ID 

Char: 

ESC 

— 

*“ 

— ^ 

Key: 

[7] 

[8] 

[9] 

[/] 

Code: 

$37 

$38 

$39 

$1E 

Char: 

7 

8 

9 

t 

Key: 

[M 

[5] 

[6] 

[,] 

Code: 

$34 

$35 

$36 

$1F 

Char: 

4 

5 

6 


Key: 

[1] 

[2] 

[3] 

[E] 

Code: 

$31 

$32 

$33 

[n] 

Char: 

1 

2 

3 

[t] 

[e] 

Key: 

[ 

0 ] 

[•] 

[r] 

Code: 

$30 

$2E $03. 

Char: 


0 

• 

ETX 


(a) Unshifted 


Key: 

[Clear] 

["] 

[+] 

[*] 

Code: 

$1B 

$2D 

$2B 

$2A 

Char: 

ESC 

— 

+ 

* 

Key: 

[7] 

[8] 

[9] 

[/] 

Code: 

$37 

$38 

$39 

$2F 

Char: 

7 

8 

9 

/ 

Key: 

[4] 

[5] 

[6] 

[,] 

Code: 

$34 

$35 

$36 

$2C 

Char: 

4 

5 

6 

9 

Key: 

[1] 

[2] 

[3] 

[E] 

Code: 

$31 

$32 

$33 

[n] 

Char: 

1 

2 

3 

[t] 





[e] 

Key: 

[ 

0 ] 

M 

[r] 

Code: 

$30 

$2E 

$03 

Char: 


0 

• 

ETX 


(b) Shift Key Down 


Standard Character Codes for Macintosh Keypad 
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Second 

digit First digit 


• 

0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

c 

D 

E 

F 

0 1 

0 

16 

32 

48 

64 

80 

96 

112 

128 

144 

160 

176 

192 

208 

224 

240 

1 | 

1 

17 

33 

49 

65 

81 

97 

113 

129 

145 

161 

177 

193 

209 

225 

241 

2 I 

2 

18 

34 

50 

66 

82 

98 

114 

130 

146 

162 

178 

194 

210 

226 

242 

3 I 

3 

19 

35 

51 

67 

83 

99 

115 

131 

147 

163 

179 

195 

211 

227 

243 

4 I 

4 

20 

36 

52 

68 

84 

100 

116 

132 

148 

164 

180 

196 

212 

228 

244 

5 I 

5 

21 

37 

53 

69 

85 

101 

117 

133 

149 

165 

181 

197 

213 

229 

245 

6 I 

6 

22 

38 

54 

70 

86 

102 

118 

134 

150 

166 

182 

198 

214 

230 

246 

7 | 

7 

23 

39 

55 

71 

87 

103 

119 

135 

151 

167 

183 

199 

215 

231 

247 

8 I 

8 

24 

40 

56 

72 

88 

104 

120 

136 

152 

168 

184 

200 

216 

232 

248 

9 I 

9 

25 

41 

57 

73 

89 

105 

121 

137 

153 

169 

185 

201 

217 

233 

249 

A I 

10 

26 

42 

58 

74 

90 

106 

122 

138 

154 

170 

186 

202 

218 

234 

250 

B | 

11 

27 

43 

59 

75 

91 

107 

123 

139 

155 

171 

187 

203 

219 

235 

251 

c 1 

12 

28 

44 

60 

76 

92 

108 

124 

140 

156 

172 

188 

204 

220 

236 

252 

D I 

13 

29 

45 

61 

77 

93 

109 

125 

141 

157 

173 

189 

205 

221 

237 

253 

E I 

14 

30 

46 

62 

78 

94 

110 

126 

142 

158 

174 

190 

206 

222 

238 

254 

F I 

15 

31 

47 

63 

79 

95 

111 

127 

143 

159 

175 

191 

207 

223 

239 

255 


Table 7. Hexadecimal/Decimal Conversion Table 
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SUMMARY OF THE EVENT MANAGER 


CONST nullEvent 
mouseDown 
mouseUp 
keyDown 
keyUp 
autoKey 
updateEvt 
diskEvt 
activateEvt 
abortEvt 
networkEvt 
driverEvt 
applEvt 
app2Evt 
app3Evt 
app4Evt 


nullMask 

mDownMask 

mUpMask 

keyDownMask 

keyUpMask 

autoKeyMask 

updateMask 

diskMask 

activMask 

abortMask 

networkMask 

driverMask 

applMask 

app2Mask 

app3Mask 

app4Mask 


1 ; 

2 ; 

4; 

8 ; 

16; 

32; 

64; 

128; 

256; 

512; 

1024; 

2048; 

4096; 

8192; 

16384; 

-32768; 


everyEvent = -1; 


TYPE EventRecord = RECORD 

what: 


{null} 

{mouse down} 

{mouse up} W j H 

{key down} * 1 

{key up} , 

{auto-key} 

{update} 

{disk inserted} 
{activate} 

{abort} 

{network} 

{I/O driver} 

{application-defined} 

{application-defined} 

{application-defined} 

{application-defined} 




^ A46U^Jj6cOtA 


{null} 

{mouse down} 

{mouse up} 

{key down} 

{key up} 

{auto-key} 

{update} 

{disk inserted} 
{activate} 

{abort} 

{network} 

{I/O driver} 
{application-defined} 
{application-defined} 
{ appl ica t ion-def ined } 
{application-defined} 



what: INTEGER; 

message: Longlnt; 


when: Longlnt; 

where: Point; 

modifiers : INTEGER 
END; 


KeyMap = PACKED ARRAY [ 1 . .128] OF BOOLEAN; 
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Accessing Events 

FUNCTION GetNextEvent (eventMask: INTEGER; VAR theEvent: EventRecord) : 

BOOLEAN; 

FUNCTION EventAvail (eventMask: INTEGER; VAR theEvent: EventRecord) : 

BOOLEAN; 


Posting and Removing Events 

PROCEDURE PostEvent (eventCode: INTEGER; eventMsg: Longlnt); 
PROCEDURE FlushEvents (eventMask, stopMask: INTEGER); 


Reading the Mouse 


PROCEDURE GetMouse 
FUNCTION Button : 
FUNCTION StillDown : 
FUNCTION WaitMouseUp 


(VAR mouseLoc: 
BOOLEAN; 
BOOLEAN; 
BOOLEAN; 


Point) ; 


Reading the Keyboard and Keypad 

PROCEDURE GetKeys (VAR theKeys: KeyMap) ; 


Miscellaneous Utilities 


PROCEDURE SetEventMask (theMask: INTEGER); 
FUNCTION TickCount : Longlnt; 
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GLOSSARY 


abort event: An event generated when the user presses a special 
combination of keys *** (tentatively Command-.) ***, or when the Event 
Manager's journaling mechanism wants a program to prepare for replaying 
a journal . 

activate event: An event generated by the Window Manager when a window 
changes from active to inactive or vice versa. 

auto-key event: An event generated periodically when the user presses 
and holds down a key on the keyboard or keypad. 

character code: An integer representing the character that a key or 
combination of keys on the keyboard or keypad stands for. 

configuration routine: A machine-language routine that defines a 
particular keyboard configuration by translating a key code, together 
with the state of the modifier keys, info a corresponding character 
code. 

disk inserted event: An event generated when the user inserts a disk 
in a disk drive. 

event: A notification to an application program of some occurrence 

that the program must respond to. 

event code: An integer representing a particular type of event. 

event mask: A parameter passed to an Event Manager routine specifying 
which types of event the routine is to be applied to. 

event message: A field of an event record containing information 
specific to the particular type of event. 

event queue: The Event Managers list of pending events waiting to be 
processed. 

event record: The internal representation of an event, where the Event 
Manager stores all pertinent information about that event. 

I/O driver event: An event generated by one of the Macintosh's input/ 
output drivers. *** (Not yet implemented.) *** 

journal: A record of all of a program's interactions with the Event 
Manager over a period of time, which can be played back in order to 
reproduce the original session. 

keyboard configuration: A resource that defines a particular keyboard 
layout by associating a character code with each key or combination of 
keys on the keyboard or keypad. 
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keyboard event: An event generated when the user presses, releases, or 
holds down a key on the keyboard or keypad; any key down, key up, or 
auto-key event. 

key code: An integer representing a key on the keyboard or keypad, 
without reference to the character that key stands for. 

key down event: An event generated when the user presses a key on the 
keyboard or keypad. 

key up event: An event generated when the user releases a key on the 
keyboard or keypad. 

modifier key: A key (Shift, Caps Lock, Option, or Command) that 
generates no keyboard events of its own, but changes the meaning of 
those generated by other keys. 

mouse down event: An event generated when the user presses the mouse 
button. 

mouse up event: An event generated when the user releases the mouse 
button. 

network event: An event generated by the Macintosh s network driver. 
*** (Not yet implemented.) *** 

null event: An event returned by the Event Manager when it has no 
other events to report. 

post: To place an event in the event queue for later processing. 

system event mask: A global event mask that controls which types of 
event get posted into the event queue. 

update event: An event generated by the Window Manager when a window s 
contents need to be redrawn. 
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See Also: Macintosh User Interface Guidelines 

The Memory Manager: A Programmer's Guide 
Macintosh Operating System Reference Manual 
QuickDraw: A Programmer's Guide 
The Resource Manager: A Programmer's Guide 
The Menu Manager: A Programmer's Guide 


Modification History: 
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First Draft (ROM 3.0) 
Second Draft (ROM 7) 


C. Rose 4/20/83 
C. Rose 4/22/83 
B. Hacker 2/7/84 


ABSTRACT 

The Font Manager is the part of the Macintosh User Interface Toolbox 
that supports the use of various character fonts when you draw text with 
QuickDraw. This manual Introduces you to the Font Manager and describes 
the routines your application can call to get font information. It also 
describes the data structures of fonts and discusses how the Font 
Manager communicates with QuickDraw. 


Summary of significant changes and additions since last version: 

- A new routine, SwapFont , has been documented (page 11). 

- A description of the method of communication between the Font 
Manager, QuickDraw, and device drivers has been added (page 11). 

- A section describing the format of a font, including font records, 
has been added (page 15). 
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ABOUT THIS MANUAL 


The Font Manager Is the part of the Macintosh User Interface Toolbox 
that supports the use of various character fonts when you draw text 
with QuickDraw. This manual Introduces you to the Font Manager and 
describes the routines your application can call to get font 
information. It also describes the data structures of fonts and 
discusses how the Font Manager communicates with QuickDraw. *** 
Eventually this will become part of a comprehensive manual describing 
the entire Toolbox and Operating System. *** 

(hand) 

This manual describes version 7 of the ROM. If you're 
using a different version, the Font Manager may not work 
as discussed here. 

Like all documentation about Toolbox units, this manual assumes you're 
familiar with the Macintosh User Interface Guidelines, Lisa Pascal, and 
the Macintosh Operating System's Memory Manager. You should also be 
familiar with: 

■ Resources, as described in the Resource Manager manual 

- The basic concepts and structures behind QuickDraw, particularly 
bit images and how to draw text 

This manual is intended to serve the needs of both Pascal and assembly- 
language programmers. Information of Interest to assembly-language 
programmers only is Isolated and labeled so that Pascal programmers can 
conveniently skip it. 

The manual begins with an overview of the Font Manager and what you can 
do with it. It then discusses the font numbers by which fonts are 
identified, the characters in a font, and the scaling of fonts to 
different sizes. Next, a section on using the Font Manager introduces 
its routines and tells how they fit into the flow of your application. 
This is followed by detailed descriptions of Font Manager procedures 
and functions, their parameters, calling protocol, effects, side 
effects, and so on. 

Following these descriptions are sections that will not interest all 
readers. There's a discussion of how QuickDraw and the Font Manager 
communicate, followed by a section that describes the format of the 
data structures used to define fonts, and how QuickDraw uses the data 
to draw characters. Next is a section that gives the exact format of 
fonts in a resource file. 

Finally, there's a summary of the Font Manager, for quick reference, 
followed by a glossary of terms used in this manual. 
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ABOUT THE FONT MANAGER : 

The main function of the Font Manager is to provide font support for 
QuickDraw* To the Macintosh user, font means the complete set of 
characters of one typeface; it doesn't include the size of the 
characters, and usually doesn't include any stylistic variations (such 
as bold and italic)* 

(hand) 

Usually fonts are defined in the normal style and 
stylistic variations are applied to them; for example, 
the italic style simply slants the normal characters. 

However, fonts may be designed to include stylistic 
variations in the first place. 

The way you identify a font to QuickDraw or the Font Manager is with a 
font number * Every font also has a name (such as "New York") that's 
appropriate to include in a menu of available fonts. 

The size of the characters , called the font size , is given^in points* 
Here this term doesn't have the same meaning as the "point" that's an 
intersection of lines on the QuickDraw coordinate plane, but instead is 
a typographical term that stands for approximately 1/72 inch. The font 
size measures the distance between the ascent line of one line of text 
and the ascent line of the next line of single-spaced text (see Figure 
1). It assumes 80 pixels per inch, the approximate resolution of the 
Macintosh screen. For example, since an Imagewriter printer has twice 
the resolution of the screen, high— resolution 9— point output to the 
printer is actually accomplished with an 18— point font. 


font I 
si 26 | 


ascent line 




Q 


■ base line 
‘•tdescent line 
'-leading 


n 


Figure 1. Font Size 
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(hand ) 

Because measurements cannot be exact on a bit - mapped 
output device, the actual font size may be slightly 
different from what it would be in normal typography. 

Whenever you call a QuickDraw routine that does anything with text, 
QuickDraw passes the following information to the Font Manager: 

- The font number. 

- The character style, a set of stylistic variations. The empty set 
Indicates normal text. (See the QuickDraw manual for details.) 

- The font size. The size may range from 1 point to 127 points, but 
for readability should be at least 6 points. 

- The horizontal and vertical scaling factors , each of which is 
represented by a numerator and a denominator (for example, a 
numerator of 2 and a denominator of 1 indicates 2 — to - 1 scaling in 
that direction). 

- A Boolean value indicating whether the characters will actually be 
drawn or not. They will not be drawn, for example, when the 
QuickDraw function CharWidth is called (since it only measures 
characters) or when text is drawn after the pen has been hidden 
(such as by the HidePen procedure or the OpenPicture function, 
which calls HidePen). 

- ^ number specifying the device on which the characters will be 
drawn or printed. The number 0 represents the Macintosh screen. 
The Font Manager can adapt fonts to other devices. 

Given this information, the Font Manager provides QuickDraw with 
information describing the font and— if the characters will actually be 
drawn - “the bits comprising the characters. 

Fonts are stored as resources in resource files; the Font Manager calls 
^ the Resource Manager to read them into memory. System-defined fonts 

are stored in the system resource file. You may define your own fonts 
with the aid of the Resource Editor and include them in the system 
resource file so they can be shared among applications. *** (The 
Resource Editor doesn't yet exist, but an interim Font Editor is 
available from Macintosh Technical Support.) *** In special cases, you 
may want to store a font in an application's resource file or even in 
the resource file for a document. It's also possible to store only the 
character widths and general font information, and not the bits 
comprising the characters, for those cases where the characters won t 
actually be drawn. 

A font may be stored in any number of sizes in a resource file. If a 
size is needed that's not available as a resource, the Font Manager 
scales an available size. 
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Fonts occupy a large amount of storage: a 12-point font typically 
occupies about 3K bytes, and a 24— point font, about 10K bytes; fonts 
for use on a high-resolution output device can take up four times as 
much space as that (up to a maximum of 32K bytes)* Fonts normally are 
purgeable, which means they may be removed from the heap when space is 
required by the Memory Manager* If you wish, you can call a Font 
Manager routine to make a font temporarily unpurgeable* 

There are also routines that provide information about a font* You can 
find out the name of a font having a particular font number, or the 
font number for a font having a particular name* You can also learn 
whether a font is available in a certain size or will have to be scaled 
to that size* 


FONT NUMBERS 


The Font Manager Includes the following font numbers for identifying 
system-defined fonts: 


CONST systemFont * 0 


applFont - 1 
newYork “ 2 
geneva “ 3 
monaco - 4 
Venice - 5 
london ** 6 
athens ■ 7 
sanFran - 8 
toronto ■ 9 


{system font) 
{application font) 


Font number 0 refers to the system font , so called because it's the 
font used by the system (for drawing menu titles and commands in menus, 
for example)* The name of the system font is Chicago* The size of 
text drawn by the system in this font is fixed at 12 points (called the 
system font size ) . 

Font number 1 represents the application font , which is a suitable font 
for general use by the application* Unlike the system font, the 
application font isn't a separate font with its own typeface, but is 
essentially a reference to another font — New York, by default* *** In 
the future, there will be a way for the user to change the default, 
perhaps through the Control Panel desk accessory* *** 


Assembly-language note : The font number of the default 
application font is stored in parameter RAM, in the system 
global spFont* You can change the application font via the 
system global apFontID, which contains the font number of the 
current application font* 
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CHARACTERS IN A FONT 


A font can consist of up to 255 distinct characters; not all characters 
need be defined in a single font* Figure 2 on the following page shows 
the standard printing characters on the Macintosh and their ASCII codes 
(for example , the ASCII code for "A" is 41 hexadecimal, or 65 decimal)* 

In addition to its maximum of 255 characters, every font contains a 
missing symbol that's drawn in case of a request to draw a character 
that's missing from the font* 


FONT SCALING 


The information QuickDraw passes to the Font Manager includes the font 
size and the scaling factors QuickDraw wants to use* The Font Manager 
determines the font information to return to QuickDraw by looking for 
the exact size needed among the sizes stored for the font. If the 
exact size requested isn't available, it then looks for a nearby size 
that it can scale. 

1* It looks first for a font that's twice the size, and scales down 
that size if there is one* 

2* If there's no font that's twice the size, it looks for a font 
that's half the size, and scales up that size if there is one* 

3* If there's no font that's half the size, it looks for a larger 

size of the font, and scales down the next larger size if there is 
one. 

4. If there '8 no larger size, it looks for a smaller size of the 
font, and scales up the closest smaller size if there is one. 

5. If the font isn't available in any size at all, it uses the 
application font instead, scaling the font to the proper size. 

6* If the application font isn't available in any size at all, it 

uses the system font instead, scaling the font to the proper size. 

Scaling looks best when the scaled size is an even multiple of an 
available size. 


Assembly-language note ; You can use the system global 
f ScaleDisable to defeat scaling, if desired. Normally, 
fScaleDisable is 0. If you set it to a nonzero value, the Font 
Manager will look for the size as described above but will 
return the font unsealed. 
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sp stands for a space. 

t-i stands for a nonbreaking space, same width as numbers. 

The first four characters are only in the system font (Chicago). 

The shaded characters are only in the Geneva, Monaco, and system fonts. 


Figure 2. Font Characters 
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USING THE FONT MANAGER ' 

This section introduces you to the Font Manager routines and how they 
fit into the general flow of an application program* The routines 
themselves are described in detail in the next section. 

The InitFonts procedure initializes the Font Manager; you should call 
it after initializing QuickDraw but before initializing the Window 
Manager. 

You can set up a menu of fonts in your application by using the Menu 
Manager procedure AddResMenu (see the Menu Manager manual for details). 
When the user chooses a menu item from the font menu, you call the Menu 
Manager procedure Getltem to get the name of the corresponding font, 
and then the Font Manager function GetFNum to get the font number. The 
GetFontName function does the reverse of GetFNum: given a font ID, it 
returns the font name. 

In a menu of font sizes in your application, you may want to let the 
user know which sizes the current font is available in and therefore 
will not require scaling. You can call the RealFont function to find 
but whether a font is available in a given size. 

If you know you'll be using a font a lot and don't want it to be 
purged, you can use the SetFontLock procedure to make the font 
unpurgeable during that time. 

Advanced programmers who want to write their own font editors or 
otherwise manipulate fonts can access fonts directly with the SwapFont 
function. 


FONT MANAGER ROUTINES 

This section describes all the Font Manager procedures and functions. 
The routines are presented in their Pascal form; for information on 
'’***'') using them from assembly language, see the *** forthcoming *** manu al 



PROCEDURE InitFonts; 

InitFonts initializes the Font Manager. If the system font isn't 
already in memory, InitFonts reads it into memory. Call this procedure 
once before all other Font Manager routines or any Toolbox routine that 
will call the Font Manager. 
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Assembly-language note : InitFonts also sets the current 
application font to the default application font (by setting the 
system global apFontID to the font number stored in parameter 
RAM in the system global spFont). 


Getting Font Information 


PROCEDURE GetFontName (fontNum: INTEGER; VAR theName: Str255); 

GetFontName returns in theName the name of the font having the font 
number fontNum. If there's no such font, GetFontName returns the empty 
string. 


Assembly— language note : The macro you invoke to call 
GetFontName from assembly language is named _GetFName. 


PROCEDURE GetFNum (fontName: Str255; VAR theNum: INTEGER); 

GetFNum returns in theNum the font number for the font having the given 
fontName. If there's no such font, GetFNum returns 0. 

FUNCTION RealFont (fontNum: INTEGER; size: INTEGER) : BOOLEAN; 

RealFont returns TRUE if the font having the font number fontNum is 
available in the given size in a resource file, or FALSE if the font 
has to be scaled to that size. 


Keeping Fonts in Memory 


PROCEDURE SetFontLock (lockFlag: BOOLEAN); 

SetFontLock applies to the font in which text was most recently drawn; 
it makes the font unpurgeable if lockFlag is TRUE or purgeable if 
lockFlag is FALSE. Since fonts are normally purgeable, this procedure 
is useful for making a font temporarily unpurgeable. 
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Advanced Routine 


The following low-level routine will not normally be used by an 
application directly, but may be of interest to advanced programmers 
who want to bypass the QuickDraw routines that deal with text* 


FUNCTION SwapFont (inRec: FMInput) : FMOutPtr; 

SwapFont returns a pointer to an FMOutput record containing the size, 
style, and other information about an adapted version of the font 
requested in the given FMInput record* (FMInput and FMOutput records 
are explained in the following section*) SwapFont is called by 
QuickDraw every time a QuickDraw routine that does anything with text 
is used* If you want to call SwapFont yourself, you must build an 
FMInput record and then use the returned pointer to access the 
resulting FMOutput record* 


COMMUNICATION BETWEEN QUICKDRAW AND THE FONT MANAGER 

This section describes the data structures that allow QuickDraw and the 
Font Manager to exchange information* It also discusses the 
communication that may occur between the Font Manager and the driver of 
the device on which the characters are being drawn or printed* You can 
skip this section if you want to change fonts, character style, and 
font sizes by calling QuickDraw and aren't interested in the lower- 
level data structures and routines of the Font Manager* 

Whenever you call a QuickDraw routine that does anything with text, 
QuickDraw requests information from the Font Manager about the 
characters* The Font Manager performs any necessary calculations and 
returns the requested information to QuickDraw* As illustrated in 
Figure 3, this information exchange occurs via two data structures, a 
font input record (type FMInput) and a font output record (type 
FMOutput)* 
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TYPE FMInput - PACKED RECORD 


family: 

INTEGER; 

{font number) 

size: 

INTEGER; 

{font size) 

face: 

Style ; 

{character style) 

needBits: 

BOOLEAN; 

{TRUE if drawing) 

device : 

INTEGER; 

{output device) 

numer: 

Point; 

{numerators of scaling factors) 

denom: 

Point 

{denominators of scaling factors) 


END; 


The first three fields contain the font number , size, and character 
style that QuickDraw wants to use* The needBits field indicates 
whether the characters actually will be drawn or not* If the 
characters are being drawn, all of the information describing the font, 
including the bit image comprising the characters, will be read into 
memory. If the characters aren't being drawn and there's a resource 
consisting of only the character widths and general font information, 
that resource will be read Instead. 

As shown in Figure 4, the high-order byte of the device field contains 
the low-order byte of the reference number for the device driver (the 
high-order byte of the reference number is $FF). The low-order byte of 
the device field contains a device subclass , which is passed on to the 
device driver and may be used as a means of distinguishing different 
kinds of output on the same device (for example, high resolution 
vs* low resolution). The value 0 in the device field represents the 
Macintosh screen. 
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15 87 0 


reference number 

device subclass 

1 " M 


8 bits 8 bits 

Figure 4. Device Field 


The numer and denom fields contain the scaling factors to be used; 
numer.v divided by denom. v gives the vertical scaling, and numer. h 
divided by denom.h gives the horizontal scaling. 

The Font Manager takes the FMInput record and asks the Resource Manager 
for the font. If the requested size isn't available, the Font Manager 
scales another size to match (as described previously). 

Then, if the device field is nonzero, the Font Manager calls the device 
driver' 8 status routine to get the device's font characterization table 
*** which will be documented in a future version of this manual ***. 

The Font Manager takes the information in the font characterization 
table and determines the optimum ascent, descent, leading, and ways of 
doing stylistic variations on that device, so that the highest quality 
printing or drawing available will be produced. It then stores this 
information in a font output record: 

TYPE FMOutput * PACKED RECORD 


errNum: 

INTEGER; 

{not used} 

fontHandle: 

Handle; 

{handle to font record} 

bold: 

Byte; 

{bold factor} 

italic: 

Byte; 

{italic factor} 

ulOffset: 

Byte; 

{underline offset} 

ulShadow: 

Byte; 

{underline shadow} 

ulThick: 

Byte; 

{underline thickness} 

shadow: 

Byte; 

{shadow factor} 

extra : 

SignedBy te ; 

{not used} 

ascent : 

Byte; 

{ascent} 

descent : 

Byte; 

{descent} 

widMax: 

Byte; 

{maximum character width} 

leading : 

SignedBy te ; 

{leading} 

unused : 

Byte; 

{not used} 

numer: 

Point ; 

{numerators of scaling factors} 

denom: 

Point 

{denominators of scaling factors} 


END; 


ErrNum is reserved for future implementation, and is currently zero. 
FontHandle is a handle to the font record of the font, as described in 
the next section. Bold, italic, ulOffset, ulShadow, ulThick, and 
shadow are all fields that modify the way stylistic variations are 
done. Ascent, descent, widMax, and leading are the same as the fields 
of the Fontlnfo record returned by the QuickDraw procedure GetFontlnfo. 
Numer and denom contain the scaling factors. 


2/7/84 Rose-Hacker 


CONFIDENTIAL 


/FMGR/FONT.D 




14 


Font Manager Programmer's Guide 


Just before returning this record to QuickDraw, the Font Manager calls 
the device driver's control routine to allow the driver to make any 
final modifications to the record* Finally, the font information is 
returned to QuickDraw via a pointer to the record, defined as follows: 

TYPE FMOutPtr - “FMOutput; 


As sembly-language note : If you want to make your own assembly- 
language calls to the device driver's status routine, the 
parameter block pointed to by A0 must contain 8 in the csCode 
field (a word located at 26(A0)), and the parameters (starting 
at 28(A0)) must be a pointer to where the device driver should 
put the font characterization table, and a word containing the 
value of the font input record's device field* If you call the 
device driver's control routine, 8 is again passed in the csCode 
field, and the parameters must be a pointer to the font output 
record and a word containing the value of the device field* 
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FORMAT OF A FONT 


This section describes the data structure that defines a font; read it 
if you're going to define your own fonts with the Resource Editor or 
write your own font editor* 


Each character in a font is defined by pixels arranged in rows and 
columns* This pixel arrangement is called a character image ; it's the 
image inside each of the character rectangles shown in Figure 5. 


i — character width — „ 



ascent line 


_ character 

character heitfit 
rectangle 

base line 


descent line J 



character 

height 


Figure 5* Character Images 


The base line is a horizontal line coincident with the bottom of each 
character , excluding descenders* The character origin is a point on 
the base line used as a reference location for drawing the character* 
Conceptually the base line is the line that the pen is on when it 
starts drawing a character, and the characer origin is the point where 
the pen starts drawing. 

The horizontal extent of a character image is called the image width. 
The image width may or may not Include space on either side of the 
character; to minimize the amount of memory required to store the font, 
the image width should not include space. The vertical extent of the 
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character rectangle, the character height , is the number of pixels from 
the ascent line to the descent line. The character rectangle is the 
rectangle enclosing the character image; its sides are defined by the 
image width and character height. 

The image width is different from the character width , which is the 
distance to move the pen from this character's origin to the next while 
drawing - “in other words, the image width plus the amount of blank space 
to leave before the next character. 

(hand) 

If the character width is 0, the character that follows 
will be superimposed on this character (useful for 
accents, underscores, and so on). 

(hand) 

Characters whose image width is 0 (such a6 a space) can 
have a nonzero character width. 

Characters in a proportional font all have character widths 
proportional to their image width, whereas characters in a fixed-width 
font all have the same character width. 

Characters can kern ; that is, they can overlap adjacent characters. 

The first character in Figure 5 above doesn't kern, but the second one 
kerns left. 

Every font has a bit image that contains a complete sequence of all its 
character images (see Figure 6 on the following page). The number of 
rows in the bit image is equivalent to the character height. The 
character images in the font are stored in the bit image as though the 
characters were laid out horizontally (in ASCII order , by convention) 
along a common base line. 

The bit image doesn't have to contain a character image for every 
character in the font. Instead, any characters missing from the font 
are omitted from the bit image, and a missing symbol is drawn instead. 
The missing symbol is stored in the bit image after all the other 
character images. 

(eye) 

Every font must have a missing symbol. 
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In addition to the terms used to describe individual characters, there 
are terms describing features of the font as a whole (see Figure 7 ). 



The font rectangle is somewhat analogous to a character rectangle. 
Imagine that all the character images in the font are superimposed with 
their origins coinciding. The smallest rectangle enclosing all the 
superimposed images is the font rectangle. 

The ascent is the distance from the base line to the top of the font 
rectangle, and the descent is the distance from the base line to the 
bottom of the font rectangle. 

The character height is the vertical extent of the font rectangle. The 
maximum character height is 127 pixels. The maximum width of the font 
rectangle is 254 pixels. 

The leading is the amount of blank space to draw between lines of 
single-spaced text— —the number of pixels between the descent line of 
one line of text and the ascent line of the next line of text. 

Finally, for each character in a font there's a character offset. As 
illustrated in Figure 8, the character offset is simply the difference 
in position of the character rectangle for a given character and the 
font rectangle. 
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offset 

Figure 8« Character Offset 


Font Records 


The information describing a font is contained in a data structure 
called a font record , which contains the following: 

- the font type (fixed-width or proportional) 

- the ASCII code of the first character and the last character in 
the font 

- the maximum character width and maximum amount any character kerns 

- the character height, ascent, descent, and leading 

- the bit image of the font 

- a location table , which is an array of words specifying the 
location of each character image within the bit image 

- an offset/width table . which is an array of words specifying the 
character offset and character width for each character in the 
font* 

For every character, the location table contains a word that specifies 
the bit offset to the location of that character's image in the bit 
image. The entry for a character missing from the font contains the 
same value as the entry for the next character. The last word of the 
table contains the offset to one bit beyond the end of the bit image 
(that is, beyond the character image for the missing symbol). The 
image width of each character is determined from the location table by 
subtracting the bit offset to that character from the bit offset to the 
next character in the table. 
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There's also one word in the offset/width table for every character: 
the high-order byte specifies the character offset and the low-order 
byte specifies the character width* Missing characters are flagged in 
this table by a word value of -1* The last word is also -1, indicating 
the end of the table. 

Figure 9 illustrates a sample location table and offset/width table 
corresponding to the bit image in Figure 6* 



location offset/ width 

table table 


Figure 9* Sample Location Table and Offset/Width Table 

A font record is a dynamic structure and is referred to by a handle 
that you can get by calling the SwapFont function or the Resource 
Manager function GetResource. The data type for a font record is as 
follows : 
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TYPE FontRec ■ RECORD 

fontType: INTEGER; {font type} 

f irstChar : INTEGER; {ASCII code of first character} 

lastChar: INTEGER; {ASCII code of last character} 

widMax: INTEGER; {maximum character width} 

kernMax: INTEGER; {maximum character kern} 

nDescent: INTEGER; {negative of descent} 

f RectWid : INTEGER; {width of font rectangle} 

chHeight: INTEGER; {character height} 

owTLoc: INTEGER; {offset to offset/width table} 

ascent: INTEGER; {ascent} 

descent: INTEGER; {descent} 

leading: INTEGER; {leading} 

rowWords: INTEGER; {row width of bit image / 2} 

{ bit Image: ARRAY { 1 .. rowWords , 1. .chHeight] OF INTEGER; } 

{bit image} 

{ locTable : ARRAY [firstChar. .lastChar+2] OF INTEGER; } 

{location table} 

{ owTable: ARRAY [firstChar. .lastChar+2] OF INTEGER; } 

{offset/width table} 

END; 

(hand) 

The variable-length arrays appear as comments because 
they're not valid Pascal syntax; they're used only as 
conceptual aids. 

The fontType field must contain one of the following predefined 
constants : 

CONST propFont - $9000; {proportional font} 
fixedFont - $B000; {fixed-width font} 

The values in the widMax, kernMax, nDescent, f RectWid, chHeight, 
ascent, descent, and leading fields all specify a number of pixels. 

KernMax indicates the largest number of pixels any character kerns, and 
should always be negative or zero, because kerning is specified by 
negative numbers (the kerned pixels are to the left of the character 
< <m S. origin). NDescent must be set to the negative of the descent. 

The owTLoc field contains a word offset from itself to the offset/width 
table; it's equivalent to 

4 + (rowWords * chHeight) + (lastChar - firstChar + 3) 

(eye) 

Remember, the offset and row width in a font record are 
given in words, not bytes. 

Normally, the Resource Editor will change the fields in a font record 
for you. You shouldn't have to change any fields unless you edit the 
font without the aid of the Resource Editor. 
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Assembly-language note : The system global romFont0 contains a 
handle to the font record for the system font* 


Font Widths 

A resource can be defined that consists of only the character widths 
and general font information — everything but the font's bit image and 
location table* If there is such a resource, it will be read in 
whenever QuickDraw doesn't need to draw the text, such as when you call 
one of the routines CharWidth, Hide Pen, or OpenPicture (which calls 
HidePen)* The FontRec data type described above, minus the rowWords, 
bit Image, and locTable fields, reflects the structure of this type of 
resource* The owTLoc field will contain 4, and the fontType field will 
contain the following predefined constant: 

CONST fontWid - $ACB0 {font width data} 


How QuickDraw Draws Text 

This section provides a conceptual discussion of the steps QuickDraw 
takes to draw characters (without scaling or stylistic variations such 
as bold and outline)* Basically, QuickDraw simply copies the character 
image onto the drawing area at a specific location* 

1. Take the initial pen location as the character origin for the 
first character. 

2* Check the word in the offset/width table for the character to see 
if it's -1. The word to check is entry (charCode - firstChar), 
where charCode is the ASCII code of the character to be drawn* 

2a* The character exists if the entry in the offset/width table 
isn't -1* Determine the character offset and character width 
from the bytes of this same word* Find the character image 
at the location in the bit image specified by the location 
table. Calculate the image width by subtracting this word 
from the succeeding word in the location table. Determine 
the number of pixels the character kerns by subtracting 
kernMax from the character offset. 

2b* The character is missing if the entry in the offset/width 

table is -1; information about the missing symbol is needed* 
Determine the missing symbol's character offset and character 
width from the next-to-last word in the offset/width table. 
Find the missing symbol at the location in the bit image 
specified by the next-to-last word in the location table 
(lastChar - firstChar +1)* Calculate the image width by 
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subtracting the next-to-last word in the location table from 
the last word (lastChar - first Char + 2). Determine the 
number of pixels the missing symbol kerns by subtracting 
kernMax from the character offset. 

3* Move the pen to the left the number of pixels that the character 
kerns. Move the pen up the number of pixels specified by the 
ascent. 

4. If the fontType field is fontWid, skip to step 5; otherwise, copy 
each row of the character image onto the screen or paper, one row 
at a time. The number of bits to copy from each word is given by 
the image width, and the number of words is given by the chHeight 
field. 

5. If the fontType field is fontWid, move the pen to the right the 
number of pixels specified by the character width. If fontType is 
fixedFont, move the pen to the right the number of pixels 
specified by the widMax field. 

6. If it's time to move down to the next line, return the pen to the 
left margin and move it down the number of bits specified by the 
leading. 

7. Return to step 2. 


FONTS IN A RESOURCE FILE 


This section contains details about fonts in resource files that most 
programmers need not be concerned about, since they can use the 
Resource Editor *** eventually *** to define fonts. It's included here 
to give background information to those who are interested. Every size 
of a font is stored as a separate resource. 

The resource type for a font is 'FONT'. The resource data for a font 
is simply a font record: 
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Humber of bytes 
2 bytes 
2 bytes 
2 bytes 
2 bytes 
2 bytes 
2 bytes 
2 bytes 
2 bytes 
2 bytes 
2 bytes 
2 bytes 
2 bytes 

2 bytes 

n bytes 


m bytes 


m bytes 


Contents 

FontType field of font record 
FirstChar field of font record 
LastChar field of font record 
WidMax field of font record 
KernMax field of font record 
NDescent field of font record 
FRectWid field of font record 
ChHeight field of font record 
OWTLoc field of font record 
Ascent field of font record 
Descent field of font record 
Leading field of font record 
RowWords field of font record 
Bit image of font 

n ■ 2 * rowWords * chHeight 
Location table of font 

m - 2 * (last Char - firstChar +3) 
Offset/width table of font 

m ■ 2 * (lastChar - firstChar +3) 


The resource type *FWID' is used to store only the character widths and 
general information for a font; its resource data is a font record 
without the rowWords field , bit image , and location table* 

As shown in Figure 10, the resource ID of a font is composed of two 
parts: bits 15 to 7 are the font number, and bits 0 to 6 are the font 
size* Thus the resource ID corresponding to a given font number and 
size is 


(128 * font number) + font size 


15 7 6 0 

font number 

font si 2 e 

a H 1 

9 bits 

7 bits 


Figure 10* Resource ID for a Font 

Since 0 is not a valid font size, the resource ID having 0 in the size 
field is used to provide only the name of the font: the name of the 
resource is the font name. For example, for a font named Griffin and 
numbered 400, the resource naming the font would have a resource ID of 
51200 and the resource name 'Griffin' • Size 10 of that font would be 
stored in a resource numbered 51210. 

Font numbers 0 through 127 are reserved for fonts provided by Apple, 
and font numbers 128 through 383 are reserved for assignment, by Apple, 
to software vendors. Each font will be assigned a unique number, and 
that font number should be used to identify only that font (for 
example, font number 9 will always be Toronto). Font numbers 384 
through 511 are available for your use in whatever way you wish. 
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Constants 


CONST systemFont “ 0 


applFont 

■a 

1 

newYork 

m 

2 

geneva 

m 

3 

monaco 

m 

4 

Venice 

m 

5 

london 

m 

6 

athens 

■ m 

7 

sanFran 

m 

8 

toronto 

m 

9 


{system font} 
{application font} 


propFont ■ $9000; {proportional font} 
fixedFont ■ $B000; {fixed-width font} 
fontWid “ $ACB0; {font width data} 


TYPE FMInput 


FMOutPtr 

FMOutput 


PACKED RECORD 


family: 

INTEGER; 

{font number} 

size: 

INTEGER; 

{font size} 

face: 

Style ; 

{character style} 

needBits: 

BOOLEAN; 

{TRUE if drawing} 

device : 

INTEGER; 

{output device} 

numer: 

Point ; 

{numerators of scaling factors} 

denom: 

Point 

{denominators of scaling factors } 

END; 



> "“FMOutput; 



' PACKED RECORD 


errNum: 

INTEGER; {not used} 

fontHandle: Handle 

; {handle to font record} 

bold: 

Byte; 

{bold factor} 

italic: 

Byte; 

{italic factor} 

ulOffset: 

Byte; 

{underline offset} 

ulShadow: 

Byte; 

{underline shadow} 

ulThick: 

Byte; 

{underline thickness} 

shadow: 

Byte; 

{shadow factor} 

extra: 

SignedByte; {not used} 

ascent : 

Byte; 

{ascent} 

descent : 

Byte; 

{descent} 

widMax: 

Byte; 

{maximum character width} 

leading : 

SignedByte; {leading} 

unused : 

Byte; 

{not used} 

numer: 

Point; 

{numerators of scaling factors} 

denom: 

Point 

{denominators of scaling factors} 


END; 
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FontRec ■ RECORD 



fontType: 

INTEGER; 

{font type} 


firstChar : 

INTEGER; 

{ASCII code of first character} 


last Char: 

INTEGER; 

{ASCII code of last character} 


widMax: 

INTEGER; 

{maximum character width} 


kernMax: 

INTEGER; 

{maximum character kern} 


nDescent : 

INTEGER; 

{negative of descent} 


fRectMax: 

INTEGER; 

{width of font rectangle} 


chHeight : 

INTEGER; 

{character height} 


owTLoc: 

INTEGER; 

{offset to offset/width table} 


ascent : 

INTEGER; 

{ascent} 


descent : 

INTEGER; 

{descent} 


leading : 

INTEGER; 

{leading} 


rowHords : 

INTEGER; 

{row width of bit image / 2} 

{ 

bit Image: 

ARRAY [1. 

• rowWords , 1. .chHeight] OF INTEGER 
{bit image} 

{ 

locTable : 

ARRAY [firstChar. .lastChar+21 OF INTEGER; 
{location table} 

{ 

owTable : 

ARRAY [firstChar.. lastChar+2} OF INTEGER 


{offset/width table} 


END; 






Routines 


Initializing the Font Manager 
PROCEDURE InitFont8; 


Getting Font Information 

PROCEDURE GetFontName (fontNum: INTEGER; VAR theName: Str255); 
PROCEDURE GetFNum (fontName: Str255; VAR theNum: INTEGER); 
FUNCTION RealFont (fontNum: INTEGER; size: INTEGER) : BOOLEAN; 


Keeping Fonts in Memory 

PROCEDURE SetFontLock (lockFlag: BOOLEAN); 


Advanced Routine 


FUNCTION SwapFont (inRec: FMInput) : FMOutPtr; 
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Assembly-Language Information 


Font Input Record Data Structure 


fmlnFamily 

fmlnSize 

fmlnFace 

fmlnNeedBits 

fmlnDevlce 

fmlnNumer 

fmlnDenom 


Font number 
Font size 
Character style 
TRUE if drawing 
Output device 

Numerators of scaling factors 
Denominators of scaling factors 


Font OutPut Record Data Structure 




fOutError 

Not used 

fOutFontHandle 

Handle to font record 

fOutBold 

Bold factor 

fOutltalic 

Italic factor 

fOutUlOffset 

Underline offset 

fOutUlShadow 

Underline shadow 

fOutUl Thick 

Underline thickness 

f Out Shadow 

Shadow factor 

fOutExtra 

Not used 

fOutAscent 

Ascent 

fOutDescent 

Descent 

fOutWidMax 

Maximum character width 

fOutLeading 

Leading 

fOutUnused 

Not used 

fOutNumer 

Numerators of scaling factors 

fOutDenom 

Denominators of scaling factors 


Font Record Data Structure 


f Format 

fMinChar 

fMaxChar 

fMaxWd 

fBBOX 

fBBOY 

fBBDX 

fBBDY 

f Length 

f Ascent 

fDescent 

f Leading 

fRaster 


Font type 

ASCII code of first character 

ASCII code of last character 

Maximum character width 

Maximum character kern 

Negative of descent 

Width of font rectangle 

Character height 

Offset to offset/width table 

Ascent 

Descent 

Leading 

Row width of bit image / 2 
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Special Macro Name 

Routine name Macro name 

Get Font Name GetFName 


System Globals 


Name Size Contents 

spFont 2 bytes Font number of default application font 

apFontID 2 bytes Font number of current application font 

fScaleDisable 1 byte Nonzero to disable scaling 

romFont# 4 bytes Handle to font record for system font 
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GLOSSARY 


application font: A font, referred to by font number 1, that's 
suitable for general use by an application — New York, by default* 

ascent: The vertical distance from a font's base line to its ascent 
line. 

ascent line: A horizontal line coincident with the top of the tallest 
characters in a font. 

base line: A horizontal line coincident with the bottom of each 
character in a font, excluding descenders. 

character height: The vertical extent of a character rectangle. 

character image: The bit image that defines a character. 

character offset: The horizontal separation between a character 
rectangle and a font rectangle. 

character origin: The point on a base line used as a reference 
location for drawing a character. 

character rectangle: The smallest rectangle enclosing an entire 
character image. 

character style: A set of stylistic variations, such as bold, italic, 
and underline. The empty set indicates normal text (no stylistic 
variations). 

character width: The distance to move the pen from one character's 
origin to the next; equivalent to the image width plus the amount of 
blank space to leave before the next character. 

descent: The vertical distance from a font's base line to its descent 
line. 

descent line: A horizontal line coincident with the bottom of the 
lowest-reaching characters in a font, including descenders. 

fixed -width font: A font whose characters all have the same width. 

font: The complete set of characters of one typeface. 

font characterization table: A table of parameters in a device driver 
that specifies how best to adapt fonts to that device. 

font number: The number by which you identify a font to QuickDraw or 
the Font Manager. 

font record: A data structure that contains all the information 
describing a font. 
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font rectangle: The smallest rectangle enclosing all the character 
images in a font, if the images were all superimposed over the same 
character origin* 

font size: The size of a font in points; equivalent to the distance 
between the ascent line of one line of text and the ascent line of the 
next of line of single-spaced text* 

image width: The horizontal extent of a character image* 

kern: To draw part of a character so that it overlaps an adjacent 
character* 

leading: The amount of blank vertical space between the descent line 
of one line of text and the ascent line of the next line of 
single-spaced text* 

location table: An array of words (one for each character in a font) 
that specifies the location of each character’s image in the font’s bit 
image* 

missing symbol: A character to be drawn in case of a request to draw a 
character that's missing from a particular font. 

offset/width table: An array of words that specifies the character 
offsets and character widths of all characters in a font* 

point: The intersection of a horizontal grid line and a vertical grid 
line on the coordinate plane, defined by a horizontal and a vertical 
coordinate; also, a typographical term meaning approximately 1/72 inch* 

proportional font: A font whose characters all have character widths 
that are proportional to their image width* 

row width: The number of bytes in each row of a bit image* 

scaling factor: A value, given as a fraction, that specifies the 
amount a character should be stretched or shrunk before it's drawn. 

style: See character style. 

system font: The font, identified by font number 0 , that the system 
uses (in menus, for example)* 

system font size: The size of text drawn by the system in the system 
font; 12 points* 
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Macintosh User Education encourages your comments on this manual. 

- What do you like or dislike about it? 

- Were you able to find the information you needed? 

- Was it complete and accurate? 

- Do you have any suggestions for improvement? 

Please send your comments to the author (indicated on the cover 
page) at 1 0460 Bandley Drive M/S 3-G, Cupertino CA 9501 4. 

Mark up a copy of the manual or note your remarks separately. 

(We'll return your marked-up copy if you like.) 


Thanks for your helpl 




INDEX 


1 


INDEX 


The page numbers are preceded by a two-letter designation of which 
manual the information is in: 


CE CoreEdit: A Programmers Guide 9/13/82 
CM Macintosh Control Manager Programmer's Guide 3/16/83 
DL The Dialog Manager: A Programmer's Guide 6/13/83 
DS The Desk Manager: A Programmer's Guide 6/14/83 
EM The Event Manager: A Programmer's Guide 6/20/83 
FM The Font Manager: A Programmer's Guide 4/22/83 
MM The Menu Manager: A Programmer's Guide 5/17/83 
PT Putting Together a Macintosh Application 7/14/83 
QD QuickDraw: A Programmer's Guide 3/2/83 
RM The Resource Manager: A Programmer's Guide 6/21/83 
SL The Segment Loader: A Programmer's Guide 6/24/83 
TU The Toolbox Utilities: A Programmer's Guide 5/16/83 
WM The Window Manager: A Programmer's Guide 3/1/83 


abort event EM-5 
action procedure CM-21, CM-22 
activate event WM-14, EM-6 
active 

control CM-8 

window WM-5 
AddPt procedure QD-65 
AddReference procedure RM-23 
AddResMenu procedure MM-16 
AddResource procedure RM-22 
alert box DL-5 
Alert function DL-21 
alert template DL-8 
alert window DL-7 
AlertTemplate data type DL-26 
AlertTHndl data type DL-27 
AlertTPtr data type DL-27 
AppendMenu procedure MM-15 
application font FM-6 
application parameters SL-4 
auto-key event EM-5 

BackColor procedure QD-46 
BackPat procedure QD-39 
backspace buffer CE-L3 
BeginSubResource procedure RM-19 
BeginUpdate procedure WM-27 
bit image QD-12 
BitAnd function TU-6 
BitClr procedure TU-5 


bitMap QD-13 
BitMap data type QD-13 
BitNot function TU-6 
BitOr function TU-6 
BitSet procedure TU-5 
BitShift function TU-6 
BitTst function TU-5 
BltXor function TU-6 
BringToFront procedure WM-21 
button CM-5 
Button function EM-19 

CalcMenuSize procedure MM-22 
CalcVis procedure WM-29 
CalcVisBehind procedure WM-29 
caret CE-11 

CautionAlert function DL-23 
CEBackSpace procedure CE-15 
CEBlinkCaret procedure CE-20 
CEBtnDown procedure CE-19 
CEBtnUp procedure CE-19 
CEChngEdit procedure CE-14 
CEChngFont procedure CE-18 
CEChngStyle procedure CE-18 
CECopy procedure CE-16 
CECut procedure CE-16 
CEDispPar procedure CE-21 
CEDoneEdit procedure CE-14 
CEForwardSpace procedure CE-15 
CEGetRnglnfo procedure CE-19 
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CEGetSelRng procedure CE-18 
CEInitEdit procedure CE-13 
CEInsertChar procedure CE-15 
CEKillEdit procedure CE-14 
CEMouseMoved procedure CE-20 
CENewPar function CE-13 
CEParCutOrCopy procedure CE-17 
CEParPaste procedure CE-18 
CEPaste procedure CE-17 
CEPrepEdit procedure CE-13 
CERedraw procedure CE-20 
CESetCaret procedure CE-20 
CESetFldRect procedure CE-20 
CESetSelRng procedure CE-18 
CEStrtEdit procedure CE-13 
Chain routine SL-6 
ChangedResource procedure RM-22 
character code EM-8 
table EM-25 

character position CE-5 
character style QD-23 
CharWidth function QD-44 
check box CM-5 
Checkltem procedure MM-21 
CheckUpdate function WM-28 
ClearMenuBar procedure MM-17 
ClipAbove procedure WM-29 
ClipRect procedure QD-38 
CloseDialog procedure DL-18 
ClosePicture procedure QD-62 
ClosePoly procedure QD-63 
ClosePort procedure QD-36 
CloseResFile procedure RM-16 
CloseRgn procedure QD-56 
CloseWindow procedure WM-19 
color drawing QD-30 
ColorBit procedure QD-46 
configuration routine EM-23 
content region WM-6 
control CM-4 

defining your own CM-25 
control definition function CM-9, CM-26 
control definition ID CM-9, CM-26 
control record CM-11 
control template CM-10 
ControlHandle data type CM-12 
ControlMessage data type CM-26 
ControlPtr data type CM-12 
ControlRecord data type CM-13 
coordinate plane QD-6 
CopyBits procedure QD-60 
CopyRgn procedure QD-55 
CouldAlert procedure DL-22 
CountMI terns function MM-23 


CountResources function RM-18 
CountTypes function RM-17 
CreateResFile procedure RM-15 
CurResFile function RM-16 
cursor QD-15 
Cursor data type QD-16 

data fork RM-6 

default button in alert box DL-5 
DeleteMenu procedure MM-16 
DeleteWindow procedure WM-29 
desk accessory DS-4 

defining your own DS-9 
desktop WM-4 

DetachResource procedure RM-19 
dial CM-6 
dialog box DL-4 

dialog record DL-12 _ 

dialog template DL-7 
dialog window DL-6 
DialogPeek data type DL-13 
DialogPtr data type DL-12 
DialogRecord data type DL-13 
DialogSelect function DL-19 
DlalogTemplate data type DL-26 
DlalogTHndl data type DL-26 
DialogTPtr data type DL-26 
DiffRgn procedure QD-57 
disabled 

dialog/alert item DL-9 

menu MM-5 

menu item MM-6, MM-12 
Disableltem procedure MM-20 
disk inserted event EM-5 
display rectangle DL-9 
DisposDialog procedure DL-18 
DisposeControl procedure CM-18 
DisposeMenu procedure MM-15 
DisposeRgn procedure QD-54 
DisposeWindow procedure WM-19 
document window WM-4 
drag region WM-6 
DragControl procedure CM-22 
DragTheRgn function TU-7 
DragWindow procedure WM-24 
DrawChar procedure QD-44 
DrawControls procedure CM-19 
DrawDialog procedure DL-21 
DrawDialog procedure DL-21 
DrawDocGrow procedure WM-14 
drawing QD-27 

color QD-30 

DrawMenuBar procedure MM-16 
DrawNew procedure WM-29 
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DravPicture procedure QD-62 
DrawString procedure QD-44 
DrawText procedure QD-44 

edit record CE-6 
edit rectangle CE-7 
EmptyRect function QD-48 
EmptyRgn function QD-58 
Enable Item procedure MM-21 
EndSubResource procedure RM-20 
EndUpdate procedure WM-27 
Equal Pt function QD-65 
EqualRect function QD-48 
EqualRgn function QD-58 
EraseArc procedure QD-53 
EraseOval procedure QD-50 
ErasePoly procedure QD-65 
EraseRect procedure QD-49 
EraseRgn procedure QD-59 
EraseRoundRect procedure QD-51 
Error Sound procedure DL-16 
event code EM-9 
event mask EM- 12 
event message EM-11 
event queue EM-6 
event record EM-9 
Event Avail function EM-18 
EventRecord data type EM-9 
Exit To Shell procedure SL-7 

FillArc procedure QD-54 
FillOval procedure QD-50 
FillPoly procedure QD-65 
FillRect procedure QD-49 
FillRgn procedure QD-59 
FillRoundRect procedure QD-52 
filterProc DL-20 
FindControl function CM-20 
FindWindow function WM-22 
Fixed data type TU-3 
fixed -point numbers TU-3 
FixMul function TU-4 
FixRatio function TU-4 
FixRound function TU-4 
FlashMenuBar procedure MM-23 
FlushEvents procedure EM-19 
FmtRun data type CE-5 
font FM-3 

scaling FM-6 
font number FM-3 
Font Info data type QD— 45 
ForeColor procedure QD— 45 
format CE-5 
Formats data type CE-5 


Frame Arc procedure QD-52 
FrameOval procedure QD— 50 
FramePoly procedure QD-64 
FrameRect procedure QD-49 
FrameRgn procedure QD-58 
FrameRoundRect procedure QD-51 
FreeAlert procedure DL-23 
FrontWindov function WM-22 

GetAppParms procedure SL-6 
GetClip procedure QD-38 
GetCRefCon function CM-25 
GetCTitle procedure CM-19 
GetCtlAction function CM-25 
GetCtlMax function CM-24 
GetCtlMin function CM-24 
GetCtlValue function CM-24 
GetDItem procedure DL-24 
GetFNum procedure FM-9 
GetFontlnfo procedure QD-45 
GetFontName procedure FM-8 
Get Icon function TU-7 
Getlnd Re source function RM-18 
Get Ind Type function RM-17 
Get Item procedure MM-20 
Get Item Icon procedure MM-21 
GetltemMark procedure MM-22 
Get ItemS tyle procedure MM-22 
GetIText procedure DL-24 
GetKeys procedure EM-20 
GetMenu function MM-15 
Get Menu Bar function MM-17 
GetMHandle function MM-23 
Get Mouse procedure EM-19 
GetNamedResource function RM-19 
GetNewControl function CM-18 
GetNewDialog function DL-18 
GetNewMBar function MM-17 
GetNewWindow function WM-18 
GetNext Event function EM-17 
GetPen procedure QD-40 
GetPenState procedure QD-41 
GetPixel function QD-68 
GetPort procedure QD-36 
GetResAttrs function RM-20 
GetResInfo procedure RM-20 
Get Resource function RM-18 
Get String function TU-4 
GetWindowPic function WM-28 
GetWMgrPort procedure WM-17 
Ge tWRefCon function WM-28 
GetWTitle procedure WM-19 
global coordinates QD-27 
global reference RM-9 
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GlobalToLocal procedure QD-66 
go-away region WM-6 
GrafDevice procedure QD-36 
grafPort QD-17 
Graf Port data type QD-18 
GrafPtr data type QD-18 
Graf Verb data type QD-71 
grow image WM-24 
grow region WM-6 
GrowWindow function WM-24 

handle QD-10 

HideControl procedure CM-19 
HideCursor procedure QD-39 
HidePen procedure QD-40 
HideWindow procedure WM-20 
HiliteControl procedure CM-19 
HiliteMenu procedure MM-19 
EiliteWindow procedure WM-21 
HiWord function TU-6 

I/O driver event EM-6 
icon number MM-10 
InitCursor procedure QD-39 
InitDialogs procedure DL-16 
Ini t Fonts procedure FM-8 
InitGraf procedure QD-34 
InitMenus procedure MM- 14 
InitPort procedure QD-35 
InitResources function RM-15 
InitWindows procedure WM-17 
insertion point CE-11 
InsertMenu procedure MM-16 
InsertWindow procedure WM-28 
InsetRect procedure QD-47 
InsetRgn procedure QD-57 
Int64Bit data type TU-7 
InvalRect procedure WM-27 
InvalRgn procedure WM-26 
InvertArc procedure QD-54 
InvertOval procedure QD-50 
InvertPoly procedure QD-65 
InvertRect procedure QD-49 
Inver tRgn procedure QD-59 
InvertRoundRect procedure QD-52 
IsDialogEvent function DL-19 
item 

dialog/alert DL-8 
menu MM-4 
item list DL-29 
item number 

dialog/alert DL-1 1 
menu MM- 13 


j ournal EM-22 
jump table SL-8 
justification CE-9 
Justification data type CE-9 

kerning QD-23 
key code EM-8 

table EM-25 
key down event EM-5 
key up event EM-5 
keyboard configuration EM-8 
keyboard event EM-5 
KeyMap data type EM-20 
KillControls procedure CM- 18 
Kill Picture procedure QD-62 
KillPoly procedure QD-63 

Launch routine SL-7 
Line procedure QD-42 
LineTo procedure QD-42 
LoadResource procedure RM— 19 
LoadSeg procedure SL-8 
local coordinates QD-25 
local reference RM-9 
Local ToGlobal procedure QD-66 
LongMul procedure TU-7 
LoWord function TU— 6 

MapPoly procedure QD-69 
MapPt procedure QD-69 
MapRect procedure QD-69 
MapRgn procedure QD-69 
margins CE-9 
menu MM-4 

defining your own MM-23 
menu bar MM-4 

menu definition procedure MM-7, MM-23 

menu ID MM-8 

menu item MM-4 

menu item number MM-13 

menu list MM-9 

menu record MM-8 

menu title MM-4 

MenuHandle data type MM-8 

Menulnfo data type MM-8 

MenuKey function MM-19 

MenuPtr data type MM-8 

MenuSelect function MM-18 

meta-characters MM-9 

minimum blink interval CE-11 

missing symbol FM-6 

modal dialog box DL-5 

ModalDialog procedure DL-20 

modeless dialog box DL-5 
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modifier key EM-7 
mouse down event EM-5 
mouse up event EM-5 
Move procedure QI^42 
MoveControl procedure CM-22 
MovePortTo procedure QD-37 
MoveTo procedure Q^42 
MoveWindow procedure WM-24 

network event EM-6 
NevControl function CM-17 
NewDialog function DL-17 
NewMenu function MM-14 
NewRgn function QD-54 
News t ring function TU-4 
NewWindow function WM-I7 
NoteAlert function DL-22 
null event EM-6 

ObscureCursor procedure QD-40 
OffsetPoly procedure QI>-63 
OffsetRect procedure QD-46 
OffsetRgn procedure QI>-56 
OpenPicture function QD-61 
OpenPoly function QD-62 
OpenPort procedure QD-35 
OpenResFile function RM-16 
OpenRgn procedure QD-55 

PacChar data type CE-5 
PaintArc procedure QD-53 
PaintBehind procedure WM-29 
PaintOne procedure WM-29 
PaintOval procedure QD-50 
PaintPoly procedure QD-64 
PaintRect procedure QD-49 
PaintRgn procedure QD-59 
PaintRoundRect procedure QD-51 
paragraph CE-5 
Paragraph data type CE-6 
ParamText procedure DL-23 
ParHndl data type CE-6 
ParPtr data type CE-6 
part code CM-10 
pattern QD-14 
Pattern data type QD-14 
pattern transfer mode QD-29 
pen characteristics QD-21 
PenMode procedure QI^41 
PenNormal procedure QD-42 
PenPat procedure QD-42 
PenSize procedure QD-41 
PicComment procedure QD-62 
PicHandle data type QD-32 


PicPtr data type QD-32 
picture QD-31 
picture comments QD-32 
Picture data type QD-31 
. picture frame QD-31 
PinRect function TU-7 
Plotlcon procedure TU-7 
point 

coordinate plane QD-7 

type size FM-4 
Point data type QD-7 
polygon QD-32 
Polygon data type QD-33 
PolyHandle data type QD-33 
PolyPtr data type QD-33 
PortSize procedure QD-37 
PostEvent procedure EM-18 
Pt2Rect procedure QD-47 
PtlnRect function QI^47 
PtlnRgn function QD-58 
PtToAngle procedure QD-48 
purgeable resource RM-7 

QDByte data type QI^-6 
QDHandle data type QD-6 
QDProcs data type QD-71 
QDProcsPtr data type QD-71 
QDPtr data type QD-6 

radio button CM-5 
Random function QD-67 
RealFont function FM-9 
Rect data type QD-9 
rectangle QD-8 
RectlnRgn function QD-58 
RectRgn procedure QD-55 
reference number RM-7 
reference value 
control CM-12 
window WM-9 
region QD-9 
Region data type QD-10 
ReleaseResource procedure RM-19 
ResError function RM-17 
resource attributes RM-10 
Resource Compiler PT-8 
resource data RM-7 
resource file RM-4 
format RM-25, RM-31 
resource fork RM-6 
resource header RM-25 
resource ID RM-9 
resource map RM-7 
resource name RM-9 


8/5/83 Rose 


CONFIDENTIAL 


/TOOLBOX/ INDEX 



6 


INDEX 


resource reference RM-9 
resource type RM-8 
resources RM-4 
ResType data type RM-8 
RgnHandle data type QD-10 
RgnPtr data type QD-10 
RlrRndl data type CE-11 
RlrPtr data type CE-11 
RmveRef erence procedure RM-23 
RmveResource procedure RM-23 
row width QD-12 
RsrcZonelnit procedure RM-15 
ruler CE-8 

RulRec data type CE-9 

SaveOld procedure WM-29 
ScalePt procedure QD-68 
ScrollRect procedure QD-59 
SectRect function QD-47 
SectRgn procedure QI>—57 
segments PT-16, SL-3 
selection range CE-11 
SelectWindow procedure WM-20 
SellText procedure DL-25 
SendBehind procedure WM-22 
SetClip procedure QD-38 
SetCRefCon procedure CM-24 
SetCTitle procedure CM-18 
SetCtlAction procedure CM-25 
SetCtlMax procedure CM-24 
SetCtlMin procedure CM-24 
SetCt lvalue procedure CM-24 
SetCursor procedure QD-39 
SetDItem procedure DL-24 
SetEmptyRgn procedure QD-55 
SetEventMask procedure EM-22 
SetFontLock procedure FM-9 
Setltem procedure MM-20 
Setltemlcon procedure MM-21 
SetltemMark procedure MM-22 
SetltemStyle procedure MM-22 
SetIText procedure DL-25 
SetMenuBar procedure MM-18 
SetMenuFlash procedure MM-22 
SetOrigin procedure QD-38 
SetPenState procedure QD-41 
SetPort procedure QD-36 
SetPortBits procedure QD-37 
SetPt procedure QD-65 
SetRect procedure QD-46 
SetRectRgn procedure QD-55 
SetResAttrs procedure RM-21 
SetResInfo procedure RM-21 
SetResLoad procedure RM-17 


SetResPurge procedure RM-24 
SetStdProcs procedure QD-71 
SetString procedure TU-4 
SetWindowPic procedure WM-28 
SetWRefCon procedure WM-28 
SetWTitle procedure WM-19 
ShowControl procedure CM-19 
ShowCursor procedure QD-39 
ShowHide procedure WM-21 
ShowPen procedure QD-40 
ShowWindow procedure WM-20 
SizeControl procedure CM-23 
SizeWindow procedure WM-25 
sound procedure DL-14 
source transfer mode QD-29 
SpaceExtra procedure QD-44 
StageList data type DL-27 
stages of an alert DL-14 
StdArc procedure QD-72 
StdBits procedure QD-72 
StdComment procedure QD-73 
StdGetPic procedure QD-73 
StdLine procedure QD-71 
StdOval procedure QD-72 
StdPoly procedure QD-72 
StdPutPic procedure QD-73 
StdRect procedure QD-72 
StdRgn procedure QD-72 
StdRRect procedure QD-72 
StdText procedure QD-71 
StdTxMeas function QI>-73 
StillDown function EM-19 
StopAlert function DL-22 
StringWidth function QD-45 
structure region WM-6 
StuffHex procedure QD-68 
Style data type QD-23 
Styleltem data type QD-23 
SubPt procedure QD-65 
system event mask EM-14 
system font FM-5 
system resource file RM-4 
system window WM-4 
SystemClick procedure DS-7 
SystemEvent function DS-8 
SystemMenu procedure DS-9 
SystemTask procedure DS— 8 

tab stops CE-9 
TestControl function CM-20 
text characteristics QD-22 
TextFace procedure QD-43 
TextFont procedure QD-43 
TextMode procedure QD-43 
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TextSize procedure QD-43 
TextWidth function QD-45 
TickCount function EM-22 
TrackControl function CM-20 
TrackGoAway function WM-23 
transfer mode QD-29 

UnionRect procedure QD-47 
UnionRgn procedure QD-57 
UnloadSeg procedure SL-6 
update event EM-6, WM-13 
update region WM-7 
UpdateResFile procedure RM-23 
UseResFile procedure RM-20 

ValidRect procedure WM-27 
ValidRgn procedure WM-27 
variation code WM-30 
VHSelect data type QD-7 
visible 

control CM-7 
window WM-9 

WaitMouseUp function EM-20 
window WM-4 

defining your own WM-30 
window class WM-9 

window definition function WM-7, WM-30 

window definition ID WM-7, WM-30 

window frame WM-6 

window list WM-9 

Window Manager port WM-6 

window record WM-8 

window template WM-8 

WindowMessage data type WM-32 

WindowPeek data type WM-iO 

WindowPtr data type WM-10 

WindowRecord data type WM-11 

word CE-8 

word wrap CE-8 

WriteResource procedure RM-24 

XorRgn procedure QD-57 
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ABSTRACT 

The Macintosh User Interface frees the user from having to remember long 
strings of command words by placing all commands in menus. With the 
menu bar and pull-down menus, the user can at any time see all available 
menu choices. This manual describes the nature of pull-down menus and 
how to implement them with the Macintosh Menu Manager. 
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ABOUT THIS MANUAL 


This manual describes the Menu Manager, a major component of the 
Macintosh User Interface Toolbox. *** Eventually it will become part 
of a larger manual describing the entire Toolbox. *** The Menu Manager 
allows you to create sets of menus, and allows the user to choose from 
the items in those menus in a manner consistent with the Macintosh User 
Interface guidelines. 

(hand) 

This manual describes version 3.0 of the ROM. If you're 
using a different version, the Menu Manager may not work 
as discussed here. 

Like all documentation about the Toolbox, this manual assumes you're 
familiar with the Macintosh User Interface Guidelines, Lisa Pascal, and 
the Macintosh Operating System's memory management. You should also be 
familiar with the following: 

- The basic concepts and structures behind QuickDraw, particularly 
character style. 

- Resources, as described in the Resource Manager Manual. 

- The Toolbox Event Manager. Some Menu Manager routines should be 
called only upon the occurrence of certain events. 

It would also be helpful to have some familiarity with a Macintosh 
application or demonstration that uses menus, as an illustration of the 
menu concepts presented here. 

The manual begins with an introduction to the Menu Manager and the 
appearance of menus on Macintosh. It then discusses the basics about 
menus: the relationship between menus and resources; some Internal 

structures related to menus; and information about how to create menus. 

Next, a section on using the Menu Manager introduces its routines and 
tells how they fit into the flow of your application. This is followed 
by detailed descriptions of all Menu Manager procedures and functions, 
their parameters, calling protocol, effects, side effects, and so on. 

Following these descriptions are sections that will not interest all 
readers: special Information for programmers who want to define their 
own menus; the exact formats of resources related to menus; and notes 
on using the "Menu Manager from assembly-language programs. 

Finally, there's a summary of the Menu Manager data structures and 
routine calls, and a glossary of special terms used in this manual. 
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ABOUT THE MENU MANAGER 

The Menu Manager supports the use of menus , an integral part of the 
Macintosh User Interface. Menus allow users to examine all choices 
available to them at any time without being forced to choose one of 
them , and without having to remember command words or special keys. 

The Macintosh user simply positions the cursor in the menu bar and 
presses the mouse button over a menu title . The application then calls 
the Menu Manager, which highlights that title (by inverting it) and 
"pulls down” the menu below it. As long as the mouse button is held 
down, the menu is displayed. Dragging the mouse through the menu items 
causes each of the items to be highlighted in turn. If the mouse 
button is released over an item, that item is "chosen". The item 
blinks briefly to confirm the choice, and the menu disappears. 

After a successful choice, the Menu Manager tells the application which 
item was chosen, and the application performs the corresponding action. 
When the application completes the action, it removes the highlighting 
from the menu title, indicating to the user that the operation is 
complete. 

If the user moves the cursor out of the menu and releases the mouse 
button, no choice is made: the menu simply disappears and the 
application takes no action. The user is never forced to complete an 
action once a menu has been pulled down. 


The Menu Bar 

The menu bar always appears at the top of the Macintosh screen and is 
20 pixels high and as wide as the screen. It appears in front of all 
windows; nothing but the cursor ever appears in front of the menu bar. 
The menu bar is white and has a thin black lower border, and the menu 
titles in it are always in the system font in a 12-point size (see 
Figure 1). 
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Figure 1. The Menu Bar 

In applications that support desk accessories, the first menu should be 
the standard Apple menu (the menu whose title is an Apple symbol)* 

This menu contains the names of all available desk accessories* When a 
desk accessory is chosen, the title of a menu belonging to it may also 
appear in the menu bar, for as long as the accessory is active, or the 
entire menu bar may be occupied by menus belonging to the desk 
accessory. (Desk accessories are discussed in detail in the Desk 
Manager manual*) 

A menu may temporarily be disabled, so that none of the items in the 
menu can be chosen* The title of a disabled menu appears dimmed in the 
menu bar (that is, drawn in gray rather than black). 

The maximum number of menu titles in the menu bar depends on the length 
and number of the titles* Ten to twelve titles is about the reasonable 
limit; any more would cause the menu bar to extend off the screen* If 
you^re having trouble fitting your menus in the menu bar, you should 
first try reviewing your menu organization and menu titles. 


Appearance of Menus 

A standard menu consists of a number of lines of text, vertically 
listed, inside a shadowed rectangle (see Figure 2). Menus always 
appear in front of everything else (except the cursor); in Figure 2, 
the menu appears in front of a document window already on the screen* 
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Figure 2. A Standard Menu 

Each line of text is one menu item that the user can choose from that 
menu. The text always appears in the system font in a 12-point size. 
Each item can have a few visual variations from the standard 
appearance : 

- A check mark (or other character) at the left of the item, to 
denote the status of the item or of the mode it controls. 

- An icon at the left of the item, to give a symbolic representation 
of the item's meaning or effect. 

- An Apple symbol and another character at the right of the item, to 
note that the item may be invoked from the keyboard (that is, it 
has a "keyboard equivalent"). *** This will be changed to a 
symbol other than the apple. *** 

- A character style other than the standard, such as bold, italic, 
underline, or a combination of these. (The QuickDraw manual gives 
a full discussion of character style.) 

- A dimmed appearance, to indicate that the item is disabled. 

The maximum number of menu items that will fit in a standard menu is 20 
(unless any item contains an icon, in which case the maximum is 
smaller). The fewer menu items you have, the simpler and clearer the 
menu appears to the user. You may include blank menu items to separate 
groups of items. 

If the standard menu does not suit your needs (for example, if you want 
more graphics or perhaps a nonlinear text arrangement) , you can always 
define a custom menu that, although visibly different to the user, 
responds to your application just like a standard menu. 
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MENUS AND RESOURCES 


The general definition of how a certain type of menu looks and behaves 
is determined by a menu definition procedure , which is usually stored 
as a resource d.n a resource file. Most applications will use the 
predefined menu definition procedure in the system resource file; 
others may write their own menu definition procedures (as described 
later in the section "Defining Your Own Menus"), 

One way to define the contents of your application's menus is to have 
your program manually create them, item by item. When you create a 
menu this way, the Menu Manager automatically assigns that menu to use 
the standard menu definition procedure and gets that procedure from the 
system resource file. The standard menu definition procedure has the 
capabilities described above: it places the text of the menu items in 
a vertical list, with each item optionally containing an icon, check 
mark, or keyboard equivalent, or being in a different character style 
or disabled. 

You can also set up your application's menus by reading them in from a 
resource file. We strongly recommend that you do this, for two 
reasons: it makes your application smaller, and it allows the menu 

items to be edited for documentation and localization without affecting 
the applications's source code. The Menu Manager allows you to read 
not only individual menus but also complete menu bars from a resource 
file. 

(hand) 

You can create menus and menu bars and store them in 
resource files with the aid of the Resource Editor *** 
eventually ***. The Resource Editor relieves you of 
having to know the exact formats of these resources in 
the file, but for interested programmers this information 
is given in the section "Formats of Resources for Menus". 

*** In the absence of the Resource Editor, you can write 
a small program to create your menus using the Menu 
Manager routine AppendMenu, and store them in a resource 
file using the standard Resource Manager calls. You can 
also use the interim Resource Compiler; see your 
Macintosh software coordinator for more information. *** 

Even if you don't store entire menus in resource files, it's a good 
idea to store the text strings they contain as resources; you can call 
the Resource Manager directly to read them in. Icons in menus are read 

from resource files; in this case, the Menu Manager calls the Resource 
Manager. 

There's one other interaction between menus and resources: a Menu 
Manager routine that will scan all open resource files for resources of 
a given type and install the resource names of all available resources 
of that type into a given menu. This Is how you fill a menu with the 
names of all available fonts, for example. 
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MENU RECORDS 

The Menu Manager keeps all the information it needs for its operations 
on a particular menu in a menu record. The menu record contains: 

- The menu ID . For menus stored in resource files, this^is the 
resource ID; for menus created by your application, it s any 
positive number (less than 32768) that you choose to identify the 
menu. 

- The menu title. 

- The contents of the menu; the text and other parts of each item. 

- The horizontal and vertical dimensions of the menu, in pixels. 

The menu items appear inside the rectangle formed by these 
dimensions; the black border and shadow of the menu appear outside 
that rectangle. 

- A handle to the menu definition procedure. 

- Flags telling whether each menu item is enabled or disabled, and 
whether the menu itself is enabled or disabled. 

The data type for a menu record is called Menulnfo. A menu is a 
dynamic, relocatable data structure and is referred to by a handle. 

The handle points to a menu pointer, which in turn points to the menu 
itself: 


TYPE MenuPtr - ^Menulnfo; 

MenuHandle 33 ^MenuPtr; 

You can store into and access all the necessary fields of a menu record 
with Menu Manager routines, so normally you don't have to know its 
exact structure. Advanced users, however — particularly those who 
define their own types of menu “ may need to know some of the field 
names. 


TYPE Menulnfo - RECORD 

menuID: INTEGER; 

menuWidth: INTEGER; 

menuHeight : INTEGER; 

menuProc: Handle; 

enableFlags: PACKED ARRAY [0..31] OF BOOLEAN; 
menuTitle: Str255 *** currently menuData *** 

{data defining the menu items} 

END; 

The menuID field contains the menu ID. 

The menuWidth and menuHeight fields contain the menu's horizontal and 
vertical dimensions, respectively. 
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The menuProc field contains a handle to the menu definition procedure 
for this type of menu. 

The 0th element of the enableFlags array is TRUE if the menu is 
enabled, or FALSE if it's disabled. The remaining elements similiarly 
determine whether each item in the menu is enabled or disabled. 

The menuTitle field contains the menu title. 

The rest of the structure contains variable-length data that defines 
the text and other parts of the menu items. For more information, see 
"Menus in a Resource File” in the section "Formats of Resources for 
Menus” . 


THE MENU LIST 

The Menu Manager keeps a list of all menu handles for menus in the menu 
bar. The user can pull down and choose from any menu whose handle is 
in this menu list . The menu bar shows the titles, in order, of all 
menus in the menu list. 

You can have menus that are not in the menu list. These menus' titles 
do not appear in the menu bar, the menus cannot be pulled down, and 
their items cannot be chosen. Such menus are useful as "reserve" menus 
to hold items not normally available to the user; these items can be 
exchanged with items in other menus, or entire reserve menus can be 
added to the menu bar. 

As a general rule, Menu Manager routines that deal specifically with 
menus in the menu list use the menu ID to refer to menus; routines that 
deal with any menus, whether in the menu list or not, use the menu 
handle to refer to menus. 


CREATING A MENU 


For an application to create menus itself, rather than read them from a 
resource file, it must call the NewMenu and AppendMenu routines of the 
Menu Manager. NewMenu creates a new menu data structure, returning a 
handle to it. AppendMenu takes a string and a handle to a menu and 

adds the itenis in the string to the end of the menu. 

The string passed to AppendMenu consists mainly of the text of the menu 
items (for a blank item, one or more spaces). Other characters in the 

string can have special meaning to the Menu Manager. These characters 

are used in conjunction with text to identify icons, set the character 
style of items, disable items, and define keyboard equivalents for 
items. These characters, called meta-characters , are interspersed in 
the string parameter of AppendMenu. The meta-characters do not appear 
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In the menu. 


Meta-character 
; or Return 

<- 

j 

/ 

( 


Meaning 

Separates items 
Item has an icon 

Item has a special character style 
Item has a check mark 
Item has a keyboard equivalent- 
item is disabled 


None, any, or all of these meta-characters can appear in the AppendMenu 
string; they are described in^ detail below. To add one text-only item 
to a menu would require a simple string without any meta-characters: 

AppendMenu( thisMenu,' Just Enough') ; 

An extreme example could use many meta-characters: 

AppendMenu( thisMenu, '(Too Much^KB! /T') ; 

This example adds to the menu an item whose text is 'Too Much', which 
is disabled, has icon number 1, is boldfaced, has a check mark, and can 
be invoked by Apple-T. Your menu items should be much simpler than 
this. 

( hand) 

If you want any of the meta-characters to appear in the 
text of a menu item, you can include them by changing the 
text of the item with the Menu Manager routine Setltem. 






Separating Items _______ 

Each call to AppendMenu can add one or many items to the menu. To add 
multiple items in the same call, use a semicolon (”;”) or a Return 
character to separate the items. The call 

AppendMenu( thisMenu , ' Cut ; Copy' ) ; 
has exactly the same effect as the calls 

AppendMenu( thisMenu, 'Cut') ; 

AppendMenu ( thisMenu , ' Copy' ) ; 


Items with Icons 

A caret ( " ~ ) followed by a digit from 1 to 9 indicates that an icon 
should appear to the left of the item's text. The digit, which is 
called the icon number , yields the resource ID of the icon in the 
resource file. The Resource Manager reserves resource IDs 257 through 
511 for menu icons; thus the Menu Manager adds 256 to the icon number 
to get the proper resource ID. 




5/17/83 Espinosa-Rose 


CONFIDENTIAL 


/MMGR/ MENUS . 2 


CREATING A MENU 


II 


If you need to install more than nine icons, you can use the 
Setltemlcon routine. 

( hand) 

The Menu Manager gets the icon number by subtracting 48 
from the ASCII code of the character following the caret 
(since, for example, the ASCII code of "1" is 49). You 
can actually follow the caret with any character that has 
an ASCII code greater than 48. 


Character Style of Menu Items 

The system font is the only font available for menus; however, you can 
vary the character style for clarity and distinction. The 
meta-character used to specify the character style is the left angle 
bracket, "<" • With AppendMenu, you can invoke one and only one of the 
stylistic variations listed below. 


item<B 

Bold 

item<I 

Italic 

item<U 

Underline 

item<0 

Outline 

item<S 

Shadow 


The SetltemStyle routine allows you to assign any character style to an 
item. For a further discussion of character style, see the QuickDraw 
manual. 


Items with Keyboard Equivalents 

Any menu item that can be chosen from a menu may also be associated 
with a key on the keyboard. Pressing this key while holding down the 
Apple key invokes the item just as if it had been chosen from the menu. 
*** Currently the ''Apple” key is labeled "COMMAND” , and in the future 
it will be something else altogether. *** 

A slash (”/") followed by a character associates that character with 
the item. That character (preceded by an Apple symbol) appears at the 
right of the item's text in the menu. For consistency between 
applications, we recommend that when the character is a letter, it be 
uppercase; note, however, that to invoke the item you can type the 
letter in either uppercase or lowercase. For example, if you specify 
'Copy/C', the Copy command can be invoked by holding down the Apple key 
and typing either C or c. 

An application that receives a key down event with the Apple key held 
down can call the Menu Manager with the typed character and receive the 
menu ID and item number of the item associated with that character. 
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Disabled Items - 

All items in a menu are usually choosable. There will be times when 
you don't want an item to be choosable initially, or even for the 
entire duration of your program (perhaps due to the incomplete state of 
the program) • ’ The meta— character that disables an item is the left 
parenthesis A disabled item appears dimmed in the menu, is not 

highlighted when the cursor moves over it, and returns 0^ when the mouse 
button is released over it. 

Blank items in a menu should always be disabled. For example, the call 

AppendMenu( thisMenu, 'Paste; ( ;Show Scrap'); 

adds two enabled menu items. Paste and Show Scrap, with a disabled 
blank item between them. 

You can change the enabled or disabled state of a menu item with the 
Disableltem and Enableltem routines. 


USING THE MENU MANAGER 


This section discusses how Menu Manager routines fit into the general 
flow of an application program and gives you an idea of which routines 
you will need to use. The routines themselves are described in detail 
in the next section. 


Before using the Menu Manager, you should previously have called the 
following initialization routines: 


InitGraf 

InitFonts 

InitWindows 

InltEvents 


(initializes QuickDraw) 
(initializes the Font Manager) 
(initializes the Window Manager) 
(initializes the Event Manager) 


To access any resource file other than the system resource file or the 
application's resource file (which are opened automatically), you must 
first open it with the Resource Manager routine OpenResFile. *** 
(Currently you must open the application's resource file 
yourself.) *** Once the necessary routines have been called, you can 
initialize the Menu Manager with the InitMenus procedure. 


Your application can then set up the menus it needs in any number of 
ways: 


— Allocate the menus with NewMenu, fill them with items using 
AppendMenu, and place them in the menu bar using InsertMenu. 

- Read the menus individually from a resource file using GetMenu, 
and place them in the menu bar using InsertMenu. 
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- Read an entire prepared menu list from a resource file with 
GetNewMBar, and place it in the menu bar with SetMenuBar. 

- Allocate a menu with NewMenu, fill it with items using AddResMenu 
to get the names of all available resources of a given type, and 
place the* menu in the menu bar using InsertMenu. 

You can in fact use AddResMenu to add items to any menu, regardless of 
how you created the menu or whether it already contains any items. 

If you call NewMenu to allocate a menu, it will store a handle to the 
standard menu definition procedure in the window record; so if you want 
the menu to be one of your own design, you must replace that handle 
with a handle to your own menu definition procedure. For more 
information, see "Defining Your Own Menus". 

At any time you can change or examine the appearance of an individual 
menu item with the Setltem and Getltem routines (and similar routines 
to set or get the item's icon, style, check mark, and so on). You can 
also change the number and order of menus in the menu list with 
InsertMenu and DeleteMenu, or change the entire menu list with 
ClearMenuBar, GetNewMBar, GetMenuBar, and SetMenuBar. 

When your application receives a mouse down event, and the Window 
Managers FindWindow function returns the inMenuBar value as a result, 
your application should call the Menu Manager's MenuSelect routine, 
supplying it with the point at which the mouse button was pressed. 
MenuSelect will pull down the appropriate menu. It will retain 
control, tracking the mouse, highlighting menu items, and pulling down 
other menus, until the user releases the mouse button. It returns a 
long integer to the application. This long Integer can be separated 
into two parts t the high-order word contains the menu ID of the menu 
that was chosen, and the low-order word contains the menu item number 
of the item that was chosen. The menu item number is the index, 
starting from 1, of the item in the menu. The entire long integer is 0 
if no item was chosen. 

- If the long integer is 0, your application should just continue to 
poll for further events. 

- If the long integer is nonzero, the application should take the 
appropriate action for when the menu item specified by the 
low-order word is chosen from the menu whose ID is in the 
high-order word. Only after the action is completely finished 
(after all dialogs, alerts, or screen actions have been taken care 
of) should your application call HiliteMenu(0) to remove the 
highlighting from the menu bar, signaling the completion of the 
action. 

Keyboard equivalents are handled in much the same manner. When your 
application receives a key down event with the Apple key held down, it 
should call the MenuKey routine, supplying it with the key that was 
pressed. MenuKey will return a long integer with the same format and 
function as that of MenuSelect, and the application can handle that 
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long integer in the manner described above. 

( hand) 

You can use the Toolbox utility routines LoWord and 
HiWord to extract the high-order and low-order words of a 
given long integer, as described in the Toolbox Utilities 
manual • 


MENU MANAGER ROUTINES 

This section describes all the Menu Manager procedures and functions, 
their parameters, and their operations* They are presented in their 
Pascal form. Assembly-language programmers should see the "Using the 
Toolbox from Assembly Language" *** doesn't exist, but see the 
QuickDraw manual *** and also "Notes for Assembly— Language Programmers" 
in this manual. 


Initialization and Allocation 


PROCEDURE InitMenus; 

InitMenus initializes all global variables used by the Menu Manager, 
sets up its internal data structures, clears the menu list, and draws 
the (empty) menu bar* Call it once before all other Menu Manager 
routines. An application should never have to call this procedure more 
than once; to start afresh with all new menus, use ClearMenuBar (see 
below) . 

( hand) 

InitWindows, which you previously called to initialize 
the Window Manager, will already have drawn the menu bar; 
InitMenus also draws the menu bar just in case it does 
happen to be called in mid-application. 


FUNCTION NewMenu (menuID: INTEGER; menuTitle: Str255) : MenuHandle; 

NewMenu allocates space for a new menu with the given menu ID and 
title, and returns a handle to it. The new menu (which is created 
empty) is not installed in the menu list. To use this menu, you must 
first call AppehdMenu to fill it with items, InsertMenu to place it in 
the menu list, and DrawMenuBar to update the menu bar to include the 
new title. 

Application menus should always have positive menu IDs. Negative 
menu IDs are reserved for menus belonging to desk accessories. No menu 
should ever have a menu ID of 0. 
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To set up the title of the Apple menu of desk accessory names, you can 
use the predefined constant appleMark (equal to 17 *** currently 128 
***, the ASCII code of the Apple symbol), as follows: 

myTitle : m ' 

myTitle{l] :■ CHR( appleMark ) ; 

Once a menu is created with NewMenu, the only way to deallocate and 
reclaim the space it uses is by calling DlsposeMenu (see below). 


FUNCTION GetMenu (menuID: INTEGER): MenuHandle; 

GetMenu returns a menu handle for the menu having the given resource 
ID. If the menu is not already in memory, GetMenu calls the Resource 
Manager to read it from the resource file into a window record in 
memory. It stores the handle to the window definition procedure in the 
window record, reading the procedure from the resource file into memory 
if necessary. 

PROCEDURE DlsposeMenu (menu: MenuHandle); 

DlsposeMenu deallocates and releases the memory used by a menu. If you 
have created temporary menus that you no longer need, use DlsposeMenu 
to get rid of them. 

( eye) 

Make sure you remove the menu from the menu list (with 
DeleteMenu) before disposing of it. Also be careful not 
to use the menu handle after disposing of the menu. 


PROCEDURE AppendMenu (menu: MenuHandle; data: Str255); 


AppendMenu adds an item or items to the end of the given menu, which 
must previously have been allocated by NewMenu or read from a resource 
file by GetMenu. The data string consists of the text of the menu 
item; it may be blank but should not be the null string. The following 
meta-characters may be embedded in the data string: 


; or Return 

( 

/ 

► 

< 


separates multiple items, 
disables the item. 

followed by a character associates a keyboard 

equivalent with the item. 

checks the item with a check mark. 

followed by B, I, U, 0, or S sets the character 

style of the item. 

followed by a digit adds an icon to the item. 


Once items have been appended to a menu, they cannot be removed or 
rearranged. AppendMenu works properly whether the menu is in the menu 
list or not. 
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PROCEDURE AddResMenu (menu: MenuHandle; theType: ResType); 

AddResMenu searches all open resource files for resources of type 
theType* It appends the names of all resources it finds to the given 
menu* Each resource name appears in the menu as an enabled item, 
without an icon or mark, and in normal character style* The standard 
calls can be used to get the name or change its appearance, as 
described below under "Controlling Items' Appearance". 

(hand) 

So that you can have resources of the given type that 
will not appear in the menu, AddResMenu does not append 
any resource names that begin with a period (".")• 

Use this procedure to fill a menu with the names of available fonts or 
desk accessories, for example. 


Forming the Menu Bar 


PROCEDURE InsertMenu (menu: MenuHandle; beforelD: INTEGER); 

InsertMenu inserts a menu into the menu list before the menu whose menu 
ID equals beforelD. If beforeID-0 (or isn't the ID of any menu in the 
menu list), the new menu is added after all others. If the menu is 
already in the menu list, InsertMenu does nothing. Be sure to call 
DrawMenuBar to update the menu bar (see below). 


PROCEDURE DrawMenuBar; 

DrawMenuBar redraws the menu bar according to the menu list, 
incorporating any changes since the last call to DrawMenuBar. Any 
highlighted menu title will remain highlighted when drawn by 
DrawMenuBar. This procedure should always be called after a sequence 
of InsertMenu or DeleteMenu calls, and after ClearMenuBar, SetMenuBar, 
or any other routine that changes the menu list. 


PROCEDURE DeleteMenu (menuID: INTEGER); 

DeleteMenu deletes a menu from the menu list. If there's no menu with 
the given menu ID in the menu list, DeleteMenu has no effect. Be sure 
to call DrawMenuBar to update the menu bar; the menu titles following 
the deleted menu will move over to fill the vacancy. 

(hand) 

DeleteMenu simply removes the menu from the list of 
currently available menus; it doesn't actually deallocate 
the menu data structure. If you mean to do this, use 
DisposeMenu after DeleteMenu. 
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PROCEDURE ClearMenuBar; 

Call ClearMenuBar to remove all menus from the menu list when you want 
to start afresh with all new menus. Be sure to call DrawMenuBar to 
update the menu bar. 

(hand) 

ClearMenuBar, like DeleteMenu, doesn^t deallocate the 
menu data structures; it merely removes them from the 
menu list. 

You don^t have to call ClearMenuBar at the beginning of your program, 
because InitMenus clears the menu list for you. 


FUNCTION GetNewMBar (menuBarlD; INTEGER) : Handle; 

GetNewMBar creates a menu list as defined by the menu bar resource 
having the given resource ID, and returns a handle to it. If the 
resource is not already in memory, GetNewMBar reads it into memory from 
the resource file. It calls GetMenu to get each of the individual 
menus • 

To make the menu list the current menu list, call SetMenuBar (below). 

To dispose of the storage occupied by the menu list, use the Operating 
System^s memory management routine DlsposeHandle. 

( eye) 

You don^t have to know the individual menu IDs to use 
GetNewMBar, but that doesn^t mean you don^t have to know 
them at all: to do anything further with a particular 
menu, you have to know its ID or its handle (which you 
can get by passing the ID to GetMHandle, as described 
later under "Miscellaneous Utilities”) . 


FUNCTION GetMenuBar : Handle; 

GetMenuBar creates a copy of the current menu list and returns a handle 
to the copy. You can then add or remove menus from the menu list (with 
InsertMenu, DeleteMenu, or ClearMenuBar), and later restore the saved 
menu list with SetMenuBar (below). To dispose of the storage occupied 
by the saved menu list, use the Operating System^s memory management 
routine DlsposeHandle. 

(eye) 

GetMenuBar doesn^t copy the menus themselves, only a list 
of their handles. Do not dispose of any menus that might 
be in a saved menu list! 
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PROCEDURE SetMenuBar (menuBars Handle); 

Given a handle to a menu list, SetMenuBar makes it the current menu 
list. You can use this procedure to restore a menu list previously 
saved by GetMenuBar, or pass it a handle returned by GetNewMBar. Be 
sure to call DrawMenuBar to update the menu bar. 


Choosing From a Menu 


FUNCTION MenuSelect (startPt: Point) : Longlnt; 

When a mouse down event occurs in the menu bar, you should call 
MenuSelect with startPt (in global coordinates) equal to the point at 
which the mouse button was pressed. MenuSelect tracks the mouse, 
pulling down menus as needed and highlighting menu items under the 
cursor. When the mouse button is released over an enabled item in an 
application menu, MenuSelect returns a long Integer whose high-order 
word is the menu ID of the menu, and whose low-order word is the menu 
item number for the item chosen (see Figure 3). It leaves the selected 
menu title highlighted. After performing the chosen task, your 
application should call HiliteMenu(0) to remove the highlighting from 
the menu title. 


menu IDs 


1 — 

1 

2 

3 10 



File 

1131 Options ) 

menu 

item 

' 1 

2 

3 

4 

Undo *V 
Cut *X 
Copy *C 


numbers 

5 

6 
7 

HHjHJQI 

snow scrap 
✓Hide Scrap 

t mousePt is where 
the cursor is pointing 


MenuSelect (mousePt) or MenuKey('Z') returns: 

I 3 I 5 ~1 

high word low word 

" ' Figure 3. MenuSelect and MenuKey 

MenuSelect returns 0 if no choice is made; this includes the case where 
the mouse button is released over a disabled menu item. 

If the mouse button is released over an enabled item in a desk 
accessory menu, MenuSelect passes the menu ID and item number to the 
Desk Manager routine SystemMenu for processing and returns 0 to your 
application. 
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( hand) 

If the global variable mBarEnable is nonzero, MenuSelect 
knows that every menu currently in the menu bar belongs 
to a desk accessory; see the Desk Manager manual for 
details. *** (The details will be in a forthcoming draft 
of that' manual. ) *** 


FUNCTION MenuKey (ch: CHAR) : Longlnt.; 

MenuKey maps the given character to the associated menu and item for 
that character. When you get a key down event with the Apple key held 
down, call MenuKey with the character that was typed (which can be 
found in the low byte of the event message). MenuKey highlights the 
appropriate menu title and returns a long integer just as MenuSelect 
does. This long integer contains the menu ID in its high-order word 
and the menu item number in its low-order word (see Figure 3 above). 
After performing the chosen task, your application should call 
HiliteMenu(0) to remove the highlighting from the menu title. 

If the given character is not associated with any enabled menu item 
currently in the menu list, the long integer returned is 0. 

Like MenuSelect, MenuKey responds to the invocation of a desk accessory 
menu item by passing the menu ID and item number to the Desk Manager 
routine SystemMenu for processing and returning 0 to your application. 

( hand) 

There should never be more than one item in the menu list 
with the same keyboard equivalent, but if there is, 

MenuKey returns the first one encountered (scanning the 
menus from left to right and their items from top to 
bottom) and ignores any subsequent ones. 


PROCEDURE HiliteMenu (menuID: INTEGER); 

HiliteMenu highlights the title of the given menu, or does nothing if 
the title is already highlighted. Since only one menu title can be 
highlighted at a time, it unhighlights any previously highlighted menu 
title. If menu ID*0 (or isn^t the ID of any menu in the menu list), 
HiliteMenu simply unhighlights whichever menu title is highlighted. 

After MenuSelect or MenuKey, your application should perform the chosen 
task and then call HiliteMenu(0) to unhighlight the chosen menu title. 
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Controlling Items ' Appearance 


PROCEDURE Setltem (menu: MenuHandle; item: INTEGER; itemString: 

Str255) ; 

Setltem changes the text of the given menu item to itemString. It 
doesn't recognize the meta-characters used in AppendMenu; if you 
include them in itemString, they will appear in the text of the menu 
item. The attributes already in effect for this item — its character 
style, icon, and so on — remain in effect. ItemString may be blank 
but should not be the null string. 

Use Setltem, for example, to flip between two alternative menu items: 
to change "Turn Grid On" to "Turn Grid Off" when the grid is already 
on. 

(hand) 

We heartily recommend against capricious changing of menu 
items. 


PROCEDURE Getltem (menu: MenuHandle; item: INTEGER; VAR itemString: 
Str255) ; 

Getltem returns the text of the given menu item in itemString. It does 
not place any meta-characters in the string. 


PROCEDURE Disableltem (menu: MenuHandle; item: INTEGER); 

Given a menu item number in the item parameter, Disableltem disables 
that menu item; given 0 in the item parameter, it disables the entire 
menu. 

Disabled menu items appear dimmed and are not highlighted when the 
cursor moves over them. MenuSelect and MenuKey return 0 if the user 
attempts to invoke a disabled item. Use Disableltem to disable all 
menu choices that are not appropriate at a given time. (An example 
from MacWrite, the Macintosh word processor, is Cut on an insertion 
point. ) 

All menu items are initially enabled, except those defined in 
AppendMenu with the "(" meta-character. 

The title of a disabled menu appears dimmed in the menu bar, and each 
menu item in it is also dimmed. 
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PROCEDURE Enableltem (menu: MenuHandle; item: INTEGER); 

Given a menu item number in the item parameter, Enableltem makes the 
item be enabled; given 0 in the item parameter, it enables the entire 
menu. (The item or menu may have been disabled with the Disableltem 
procedure, or -the item may have been disabled with the "(" 
meta-character in the AppendMenu string.) The item or menu title will 
no longer appear dimmed and can be chosen like any other enabled item 
or menu. 


PROCEDURE Checkltem (menu: MenuHandle; item: INTEGER; checked: 

BOOLEAN); 

Checkltem places or removes a check mark at the left of the given menu 
item. After you call Checkltem with checked»TRUE , a check mark will 
appear each subsequent time the menu is pulled down. Calling Checkltem 
with checked**FALSE removes the check mark. 

Menu items initially have no check marks, except those defined in 
AppendMenu with the " ! " meta-character. 


PROCEDURE Setltemlcon (menu: MenuHandle; item: INTEGER; icon: INTEGER); 

Setltemlcon associates the given menu item with an icon. It sets the 
item's icon number to the given value (an integer from 1 to 255). The 
Menu Manager calls the Resource Manager to get the corresponding icon 
when necessary. 

( eye) 

The Menu Manager adds 256 to the icon number to get the 
icon's resource ID. If you deal directly with the 
Resource Manager to read or store menu icons, be sure to 
adjust your icon numbers accordingly. 

Menu items initially have no icons, except those items defined in 
AppendMenu with the meta-character. 


PROCEDURE Getltemlcon (menu: MenuHandle; item: INTEGER; VAR icon: 
INTEGER) ; 

Getltemlcon returns the icon number associated with the given menu 
item, as an integer from 1 to 255, or 0 if the item has not been 
associated with an icon. 

( hand) 

The icon number is 256 less than the icon's resource ID. 
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PROCEDURE SetltemStyle (menu: MenuHandle; item: INTEGER; chStyle: 
Style); 

SetltemStyle changes the character style of the given menu item to 
chStyle, a set of one or more of the stylistic variations bold, italic, 
underline, outline, shadow, condense, and extend. For example: 

SetItemStyle(thisMenu,l , [bold, italic] ) ; {bold and italic} 

Menu items are initially in the normal character style, except those 
defined in AppendMenu with the "<" meta-character. 


PROCEDURE GetltemStyle (menu: MenuHandle; item: INTEGER; VAR chStyle: 
Style); 

GetltemStyle returns the character style of the given menu item in 
chStyle. 


PROCEDURE SetltemMark (menu: MenuHandle; item: INTEGER; markChar: 

CHAR); 

SetltemMark marks the given menu item in a more general manner than 
Checkltem. It allows you to place any character in the system font, 
not just the check mark, to the left of the item. You can specify some 
useful values for the markChar parameter with the following predefined 
constants: 

CONST appleMark * 17; {Apple symbol} *** currently 128 *** 

checkMark =* 18; {check mark} *** currently 129 *** 

noMark =» 0; {nothing, to remove a mark} 


PROCEDURE GetltemMark (menu: MenuHandle; item: INTEGER; VAR markChar: 
CHAR); 

GetltemMark returns in markChar whatever character the given menu item 
is marked with, or the null character if no mark is present. 


Miscellaneous Utilities 


PROCEDURE SetMenuFlash (menu: MenuHandle; count: INTEGER); 

When the mouse button is released over an enabled menu item, that item 
blinks briefly to confirm the choice. Normally your application need 
not be concerned about the duration of the blinking, but for special 
situations SetMenuFlash allows you to control the duration for all 
items in the given menu. Calling SetMenuFlash with a count of 0 
disables blinking; calling it with a count of 2 (the default value) 
will cause items to blink for about 0.1 second. A count of 3 is 
appropriate for naive user applications; values greater than that can 
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be annoyingly slow, 

( hand) 

Items in both standard and nonstandard menus blink when 
chosen. The appearance of the blinking for a nonstandard 
menu depends on the menu definition procedure , as 
described later under "Defining Your Own Menus”. 


PROCEDURE CalcMenuSize (menu: MenuHandle); 

You can use this utility procedure to recalculate the horizontal and 
vertical dimensions of a menu whose contents have been changed (and 
store them in the appropriate fields of the menu record). CalcMenuSize 
is called automatically after every AppendMenu, Setltem, Setltemlcon, 
and SetltemStyle call. 


FUNCTION CountMI terns (menu: MenuHandle) : INTEGER; 

CountMI terns returns the number of menu items in the given menu. 


FUNCTION GetMHandle (menuID: INTEGER) : MenuHandle; 

Given the menu ID of a menu currently installed in the menu list, 
GetMHandle returns a handle to that menu; given any other menu ID, it 
returns NIL. 


PROCEDURE FlashMenuBar (menuID: INTEGER); 

If menuID is 0 (or isn^t the ID of any menu In the menu list), 
FlashMenuBar inverts the entire menu bar; otherwise, it inverts the 
title of the given menu. 


DEFINING YOUR OWN MENUS 


Normally when you create a menu you get the standard type of Macintosh 
menu, as described in this manual. You may, however, want to define 
your own type of menu, such as one with more graphics or perhaps a 
nonlinear text arrangement. QuickDraw and the Menu Manager make it 
possible for you to do this. 

To define your own type of menu, you must write a menu definition 
procedure. The menu definition procedure defines the menu by 
performing basic operations such as drawing the menu. When the Menu 
Manager needs to perform one of these operations, it calls the menu 
definition procedure with a parameter that identifies the operation, 
and the menu definition procedure in turn takes the appropriate action. 
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Usually you will store the menu definition procedure in a resource 
file. If you won't be sharing it with other applications, you may want 
to store it in with your application code rather than in the resource 
file. 

When you create a menu with NewMenu, it stores a handle to the standard 
menu definition procedure in the menu record's menuProc field; you must 
replace this with a handle to your own menu definition procedure. If 
your definition procedure is in a resource file, you get the handle by 
calling the Resource Manager to read it from the resource file into 
memory. 

Instead of creating menus with NewMenu, your application may read the 
menus themselves from a resource file with GetMenu (or GetNewMBar, 
which calls GetMenu). A menu in a resource file contains the resource 
ID of its menu definition procedure. If you store the resource ID of 
your own menu definition procedure in a menu in a resource file, 

GetMenu will take care of reading the procedure into memory and storing 
a handle to it in the menuProc field of the menu record. 


The Menu Definition Procedure 

The menu definition procedure may be written in Pascal or assembly 
language; the only requirement is that its entry point be at the 
beginning. You may choose any name you wish for the procedure. Here's 
how you would declare one named MyMenu: 

PROCEDURE MyMenu (message: INTEGER; menu: MenuHandle; menuRect: 

Rect; hitPt: Point; VAR whichltem: INTEGER); 

The message parameter identifies the operation to be performed. Its 
value will be one of the following predefined constants: 

CONST mDrawMsg =» 0; {draw the menu} 

mChooseMsg *» 1; {tell what menu item was chosen and } 

{ highlight it} 

mCalcSize =* 2; {calculate the menu's dimensions } 

The menu parameter indicates the menu that the operation will affect, 
and menuRect is the rectangle in which the menu is located. 

The message mDrawMsg tells the menu definition procedure to draw the 
menu inside menuRect; the grafPort will be set up properly for this. 
(For details on drawing, see the QuickDraw manual.) The standard menu 
definition procedure figures out how to draw the menu items by looking 
in the menu record at the data that defines them; this data is 
described in detail under "Formats of Resources for Menus" below. For 
menus of your own definition, you may set up the data defining the menu 
items any way you like, or even omit it altogether (in which case all 
the information necessary to draw the menu would be in the menu 
definition procedure itself). 


f0^ 
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( eye) 

Be sure that any text in the menu is drawn in the system 
font! 

When the menu definition procedure receives the message raChooseMsg, the 
hitPt parameter is the point at which the mouse button was pressed and 
the whichltem parameter is the last item that was chosen from this 
menu. The procedure should test whether hitPt is inside menuRect and 
respond accordingly: 

- If hitPt is inside menuRect, unhighlight whichltem, highlight the 
newly chosen item, and return the item number of that item in 
whichltem. 

- If hitPt isn^t inside menuRect, unhighlight whichltem and return 

0 . 

Both hitPt and menuRect are in global coordinates. 

( hand) 

When it needs to make a chosen menu item blink, the Menu 
Manager repeatedly calls the menu definition procedure 
with the message mChooseMsg, causing the item to be 
alternately highlighted and unhighlighted. 

Finally, the message mCalcSize tells the menu definition procedure to 
calculate the horizontal and vertical dimensions of the menu and store 
them in the menuWidth and menuHeight fields of the menu record. 


FORMATS OF RESOURCES FOR MENUS 


The resource type for a menu definition procedure is 'MDEF^. The 
standard menu definition procedure has a resource ID of 0, so your own 
such procedures must have resource IDs other than 0. The resource data 
is simply the assembled code of the procedure. 

Icons in menus must be stored in a resource file under the resource 
type ^ICON' with resource IDs from 257 to 511. Strings in resource 
files have the resource type 'STR " — but note that if you follow the 
recommendation of storing entire menus in resource files, you will 
never have to store the strings they contain separately. 

The formats of menus and menu bars in resource files are given below. 
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Menus in a Resource File 

The resource type for a menu is 'MENU' . The resource ID must be 
negative for menus belonging to desk accessories and positive for other 
menus; it should never be 0. The resource data for a menu has the 
format shown below. Once read into memory, this data is stored in a 
menu record (described earlier in the "Menu Records" section). 


Number of bytes Contents 

2 bytes Menu ID (resource ID of this menu) 

2 bytes 0; placeholder for menu width 

2 bytes 0; placeholder for menu height 

2 bytes Resource ID of menu definition procedure 

2 bytes 0 (see comment below) 

4 bytes Same as enableFlags field of menu record 

1 byte Length of following title in bytes 

n bytes Characters comprising menu title 

For each menu item: 

1 byte Length of following text in bytes 

m bytes Characters comprising text of menu item 

1 byte Icon number, or 0 if no icon 

1 byte Keyboard equivalent, or 0 if none 

1 byte Character marking menu item, or 0 if none 

1 byte Character style of item's text 

1 byte 0, indicating end of menu items 

The four bytes beginning with the resource ID of the menu definition 
procedure serve as a placeholder for the handle to the procedure: When 
GetMenu is called to read the menu from the resource file, it also 
reads in the menu definition procedure if necessary, and replaces these 
four bytes with a handle to the procedure. The resource ID of the 
standard menu definition procedure is: 

CONST textMenuProc - 0; 


The resource data for a nonstandard menu can define menu items in any 
way whatsoever, or not at all, depending on the requirements of its 
menu definition procedure. If the appearance of the items is basically 
the same as the standard, the resource data might be as shown above; 
but in fact everything following "For each menu item" can have any 
desired format or can be omitted altogether. Similarly, all bits 
beyond the first of the enableFlags array may be set and used in any 
way desired by the menu definition procedure; the first bit applies to 
the entire menu and must reflect whether it's enabled or disabled. 


If your menu definition procedure does use the enableFlags array, 
menus of that type may contain no more than 31 items (1 per available 
bit); otherwise, the number of items they may contain is limited only 
by the amount of room on the screen. 

( hand) 

As described in "Using the Toolbox from Assembly 
Language" *** (doesn't exist; currently it's in "Using 
QuickDraw from Assembly Language" in the QuickDraw 
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manual) ***, the character style has bit 0 set for bold, 
bit 1 for italic, bit 2 for underline, bit 3 for outline, 
bit 4 for shadow, bit 5 for condense, and bit 6 for 
extend. If all bits are 0, the character style is 
normal. 


Menu Bars in a Resource File 

The resource type for the contents of a menu bar is 'MBAR^ and the 
resource data has the following format: 


Number of bytes 
2 bytes 
For each menu 
2 bytes 


Contents 
Number of menus 

Resource ID of menu 


NOTES FOR ASSEMBLY-LANGUAGE PROGRAMMERS 


Information about how to use the User Interface Toolbox from assembly 
language is given elsewhere. *** For now, see the QuickDraw manual. 
*** This section contains special notes of Interest to programmers who 
will be using the Menu Manager from assembly language. 

The primary aid to assembly- language programmers is a file named 
TOOLEQU.TEXT. If you use .INCLUDE to include this file when you 
assemble your program, all the Menu Manager constants, offsets to 
locations of global variables, and offsets into fields of structured 
types will be available in symbolic form. 
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SUMMARY OF THE MENU MANAGER 


CONST noMark - 0; 

appleMark ■ 17; *** currently 128 *** 
checkMark = 18; *** currently 129 *** 


mDrawMsg ■ 0 ; 
mChooseMsg ■ 1; 
mCalcSize » 2; 
textMenuProc * 0; 


TYPE MenuPtr ■ 'Menulnfo; 

MenuHandle = 'MenuPtr; 

Menulnfo ■ RECORD 

menuID: INTEGER; 

menuWidth: INTEGER; 

menuHeight: INTEGER; 

menuProc: Handle; 

enableFlags: PACKED ARRAY [0..31] OF BOOLEAN; 
menuTitle: Str255 *** currently menuData *** 

{data defining the menu items} 

END; 


Initialization and Allocation 

PROCEDURE InitMenus; 

FUNCTION NewMenu (menuID: INTEGER; menuTitle: Str255) : MenuHandle; 
FUNCTION GetMenu (menuID: INTEGER) : MenuHandle; 

PROCEDURE DisposeMenu (menu: MenuHandle); 

PROCEDURE AppendMenu (menu: MenuHandle; data: Str255); 

PROCEDURE AddResMenu (menu: MenuHandle; theType: ResType); 


Forming the Menu Bar 

PROCEDURE InsertMenu (menu: MenuHandle; beforelD: INTEGER); 

PROCEDURE DrawMenuBar; 

PROCEDURE DeleteMenu (menuID: INTEGER); 

PROCEDURE ClearMenuBar ; 

FUNCTION GetNewMBar (menuBarlD: INTEGER) : Handle; 

FUNCTION GetMenuBar : Handle; 

PROCEDURE SetMenuBar (menuBar: Handle); 


Choosing from a Menu 

FUNCTION MenuSelect (startPt: Point) : Longlnt; 
FUNCTION MenuKey (ch: CHAR) : Longlnt; 
PROCEDURE HiliteMenu (menuID: INTEGER); 
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Controlling Items ' Appearance 

PROCEDURE Setltem (menu: MenuHandle; item: INTEGER; itemString: 

Str255) ; 

PROCEDURE Getltem (menu: MenuHandle; item: INTEGER; VAR itemString: 

Str255) ; 

PROCEDURE Disableltem (menu: MenuHandle; item: INTEGER); 

PROCEDURE Enableltem (menu: MenuHandle; item: INTEGER).; 

PROCEDURE Checkltem (menu: MenuHandle; item: INTEGER; checked: 

BOOLEAN); 

PROCEDURE Setltemlcon (menu: MenuHandle; item: INTEGER; icon: INTEGER); 

PROCEDURE Getltemlcon (menu: MenuHandle; item: INTEGER; VAR icon: 

INTEGER) ; 

PROCEDURE SetltemStyle (menu: MenuHandle; item: INTEGER; chStyle: Style) 

PROCEDURE GetltemStyle (menu: MenuHandle; item: INTEGER; VAR chStyle: 

Style); 

PROCEDURE SetltemMark (menu: MenuHandle; item: INTEGER; markChar: CHAR) 

PROCEDURE GetltemMark (menu: MenuHandle; item: INTEGER; VAR markChar: 

CHAR); 


Miscellaneous Utilities 

PROCEDURE SetMenuFlash (menu: MenuHandle; count: INTEGER); 
PROCEDURE CalcMenuSize (menu: MenuHandle); 

FUNCTION COuntMItems (menu: MenuHandle) : INTEGER; 
FUNCTION GetMHandle (menuID: INTEGER) : MenuHandle; 
PROCEDURE FlashMenuBar (menuID: INTEGER); 
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GLOSSARY 

dimmed: Drawn in gray rather than black, as a disabled menu item or 

the title of a disabled menu. 

disabled: Unable to be chosen, as a menu item or an entire menu; the 
menu item or menu title appears dimmed. 

icon: A 32-by-32-bit image that graphically represents an object, 
concept, or message. 

icon number: A digit from 1 to 9 to which the Menu Manager adds 256 to 
get the resource ID of an icon associated with a menu item. 

menu: A list of menu items that appears when the user points to and 

presses a menu title in the menu bar. Dragging through the menu and 
releasing over a menu item chooses that item. 

menu bar: The horizontal strip at the top of the screen that contains 
the menu titles of all menus in the menu list. 

menu definition procedure: A procedure called by the Menu Manager when 
it needs to perform basic operations on a particular type of menu, such 
as drawing the menu. 

menu ID: For menus defined in resource files, the resource ID of the 
menu; for application menus, any positive number (less than 32768) that 
you choose to identify the menu. 

menu item: A choice in a menu, usually a command to the current 
application; in a standard Macintosh menu, a line containing text and 
possibly an icon. 

menu item number: The index, starting from 1, of a menu item in a 
menu. 

menu list: A list of menu handles for all menus in the menu bar, kept 
internally by the Menu Manager. 

menu record: The internal representation of a menu, where the Menu 
Manager stores all the information it needs for its operations on that 
menu. 

menu title: A word or phrase in the menu bar that designates one menu. 

meta-character: One of the characters ; ~ < ! / ( or Return appearing 
in the string passed to the Menu Manager routine AppendMenu, to 
separate menu items or alter the appearance of those items. 
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CHAPTER 1 

OVERVIEW OF THE OPERATING SYSTEM 


There are two main groups of routines that may be called by an 
application program — the Macintosh Operating System and the Macintosh 
User Interface Toolbox, 

A typical application program is driven by user actions, which come to 
it via the event manager portion of the operating system. The Macintosh 
computer uses a pointing device called "the mouse" as the primary device 
for obtaining input from the computer user. Application programs will 
generally be more efficient if they are oriented to using the mouse, 
rather than the keyboard, whenever possible. Both the mouse and the 
keyboard are accessed through the event mechanisms. 

Events should be the fulcrum of an application program. It is a good 
idea to organize the application program so that it responds to events 
as quickly as possible. 

The User Interface Toolbox exists mainly to help the application 
programs implement their interface with the computer user. The Toolbox 
manipulates the Macintosh f s bit-map video display, and interprets inputs 
from the event manager. It is not strictly required that the 
application program make calls to the Toolbox. However, accessing the 
Toolbox whenever possible tends to reduce both code size and development 
time, and also helps provide a consistent user interface among 
applications. 

The operating system contains the following groups of core routines: 

File and I/O Routines 

File System Routines 

Memory Management Routines 

Event Management Routines 

Vertical Retrace Management Routines 

Utility Routines 

Core routines are invoked via the "LINE 1010" emulator trap. Typically, 
this occurs when the microprocessor encounters an unimplemented 
instruction word of the form $AXnn, where nn specifies the particular 
core routine to be called. Details are given later under Core Routine 
Invocation. 

The following paragraphs provide some general information concerning 
each group of core routines. 
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File and I/O Routines 

The File and I/O Routines are those core routines that can be used to 
access devices as well as files* They operate in connection with the 
device drivers, which are described below under DRIVERS. 

Within the File and I/O group, some core routines (READ, WRITE, CONTROL, 
and STATUS, and for the File System OPEN and CLOSE) 
have the capability to operate asynchronously. In this context, 
asynchronous operation means that the microprocessor is free to perform 
other tasks while the core routine is executing. 

Asynchronous I/O requests return to the caller almost immediately, 
usually before the actual I/O is performed. The calling program may 
poll an I/O result flag (in the parameter block) to determine whether 
the I/O operation has finished. Alternatively, the calling program may 
specify a completion routine (with an address pointer in the parameter 
block) to be executed as soon as the I/O operation has been completed. 

Completion routines may be used to build asynchronous I/O processes such 
as a spooler. The user can employ the asynchonous I/O mechanism to 
double-buffer I/O requests and to interleave I/O with computation, thus 
improving performance. 


File System Routines 

The file manager* supports a simple view of files, optimized for high 
performance. The current 

structure supports volume sizes up to 32 megabytes. A file is an array 
of bytes which may be any size from zero up to the size of the volume it 
is on. A file may be read sequentially (from the beginning) or it may 
be random-accessed by using positioning parameters relative to the 
beginning of the file. 

All file manager calls may be specified as synchronous or asynchronous. 
File requests are queued. There may be only one request in progress at 
any given time. MOUNT VOLUME and UNMOUNTVOLUME are always executed 
synchronously, however, since they use the memory manager to allocate 
and deallocate memory for file system data structures. 

The file system allows for variable— length directory records. Thus it 
can support very long file names in a space-efficient manner. 

To enhance reliability, the file system uses a distributed directory. 
Each block on the disk is tagged with a file number and file offset. 
Other directory information is kept in the file label (if present). If 
a directory or other file access information is destroyed, it may be 
reconstructed by scanning the disk. A "scavenger 11 utility program will 
be provided to perform this service. 
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The disk driver included in the Macintosh computer supports 
Twiggy type disk drives. Any other disk device will be 
accessed via the serial bus, and must have a separate driver to 
access it via block-level requests (like the Twiggy driver). 

The file system can support any number of these external disks (limited 
only by memory size). 

Alternatively, an external disk may be accessed via file-level commands 
if it has enough intelligence: this approach allows different computers 
(Apple ][, Macintosh, Lisa, etc.) to share files on a common disk 
drive, even though the computers themselves may have incompatible 
directory formats. 


Memory Management Routines 

The memory manager is a set of core routines used to manage zones of 
memory. All system and application programs should access RAM by making 
calls to the memory manager. 

Individual blocks in RAM may be either relocatable or non— relocatable. 
For non— relocatable blocks, the memory manager returns the absolute 
address of the allocated block, and that block remains at the same 
address until it is explicitly de-allocated. For relocatable blocks, 
the memory manager returns a "handle" , which is a pointer to a location 
within the memory manager. At this location is a "master pointer", 
which in turn points to the allocated block. 

It is best to use relocatable blocks whenever possible, since the non- 
relocatable blocks are "islands", and tend to fragment the usable memory 
space. Non-relocatable blocks may be used, however, for permanent 
storage that is allocated at system initialization time, or for 
temporary storage that will be quickly de-allocated. 

Relocatable blocks may be temporarily locked down in memory, when 
necessary, and may also be made "purgable". Locked relocatable blocks 
have the same drawbacks as non-relocatable blocks, and should be unlocked 
as soon as possible. Purgable blocks give greater flexibility to the 
memory manager by allowing it to reclaim this space when necessary. 


Event Management Routines 

Most applications are driven by asynchronous events generated by the 
computer user — events such as moving the mouse, pressing keyboard 
keys, or inserting a diskette. The event manager collects these 
asynchronous events and presents them to the application program via the 
higher-level toolbox event routines GETNEXTEVENT and EVENTAVAIL (these 
routines allowing journaling and supply update events in addition to 
all the events supplied by the event manager).. 

Alternatively, the event manager routines GETOSEVENT and OSEVENTAVAIL may 
be called directly. 
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An application program obtains the events by calling the GETNEXTEVENT 
core routine. GETNEXTEVENT returns an event record, containing an event 
identifier and some event-specific information, plus the state of 
several system variables. These system variables include the time when 
the event occurred, the mouse position and mouse button state, and the 
states of the four keyboard meta-keys (COMMAND, CODE, SHIFT, and ALPHA 
LOCK). GETNEXTEVENT passes back events according to a pre-defined 
priority scheme. Events of the same priority are passed back according 
to their time of occurrence. If there is no event available (within a 
user-defined time interval) the GETNEXTEVENT routine returns a "null" 
event. 

Some important system-defined events are "mouse button down", keyboard 
key down", and "diskette inserted'*. Events may also be defined by the 
applications or by user-supplied drivers, via the POSTEVENT core 
routine. The event mechanism is also used for posting system errors. 
Events may be selectively removed from the event queue by the FLUSHEVENTS 
routine. 
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Vertical Retrace Management Routines 

The Macintosh system is interrupted every 1/60 second by the leading 
edge of the video generator’s vertical retrace signal. Routines may 
synchronize with this signal for such purposes as glitch-free screen 
updates. System programs and/or the user may spawn off asynchronous 
sub-programs useful for many applications. 

The vertical retrace manager is the portion of the operating system that 
determines what gets called when a vertical retrace interrupt occurs. 
Two core routines provide access to the vertical retrace facility — 
VINSTALL and VREMOVE, VINSTALL is used to install a vertical retrace 
control block. This control block contains the address of a routine (to 
be executed during the vertical retrace interval) and specifies exactly 
when and how often the routine should execute. VREMOVE is used to 
remove a control block from the group, and thus to terminate the making 
of calls to the associated routine. 

System and application programs can use the vertical retrace manager to 
spawn off mini-processes that are activated up to 60 times per second. 
One should take care however, that such processes are not too complex, 
since this would tend to degrade the performance of the mainline 
application. 

Another function performed by the vertical retrace manager is the 
incrementing of TICKS every 1/60 second. TICKS is a 32-bit unsigned 

integer residing in the system global area. System and application 
programs can use TICKs for a variety of timing functions via the TICKCOUNT 
toolbox routine. 


Utility Routines 

The utility manager contains routines that provide services such as code 
segment loading, reading from and writing to the non-volatile parameter 
RAM, reading and writing the system date and time values, delaying a 
specified number of tick counts, comparing ASCII strings, and installing 
custom core routines. Details are given in the Utility Routines 
section, below. 
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FILE AND I/O CORE ROUTINES SAXOO through $AX06 

The File and I/O Core Routines are used to control the system^s I/O 
facilities. These facilities include one or two disk drives, two serial 
ports, and the sound generator. The mouse and keyboard are supported 
through the event manager and cursor core routines, not through the I/O 
system. 

< should really make the distinction between the devices and the actual drivers 
which control them; the drivers are open/read/write/control/ status/closed, 
not the devices. Also, drivers may be layered one upon the other. The file 
system accesses files thru the disk driver> 

For I/O purposes, devices and files are opened, read, written, and closed 
through an identical interface — that is, devices look just like files to 
the programmer. The Open, Read, Write, and Close calls(in this section) can 
be used in connection with both files and I/O devices. The File Management 
Core Routines (in the next section) are used only in connection with files. 

For programming ease, File and I/O core routines are always called with AO 
pointing to a parameter block and return with DO containing a result code 
(zero if the call was successfully completed). All parameter blocks share a 
common format: the first 24 bytes are always the same. They may be organized 
into several different parameter block types: the standard I/O parameter 
block, a block for GetFilelnfo and SetFilelnfo, a block for volume-level 
calls, and a block for Control and Status calls. 

Common parameter block header 

(0) 12-byte header used by the file and I/O system 
(12) lOCompletion - completion routine address (zeroed for synchronous calls) 
(16) IOResult - final result code when the call is made asynchronously 
(18) IOFileName - pointer to Vol:Filename string 
(22) IODrvNum - drive number for drive on which volume is mounted 

Standard I/O Parameter Block (IQQElSize - 50 bytes total with header ) 

(24) lORefNum - reference number for I/O operation 

(26) IOFileType - file type field (byte) 

(27) IOPermssn - Open permissions (byte) 

(28) lONewName , I0LE0F , IOOwnBuf , IONewType - miscellaneous 4-byte field 

(32) IOBuffer - data buffer pointer 

(36) lOByteCount , IOReqCount - requested byte count 

(40) I0NumDone,I0Act Count - actual byte count completed 

(44) IOPosMode - initial file positioning mode, eol char 
(46) IOPosOffset - file position offset (long word) 
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Equates Specific to GetFilelnfo ,SetFlleInfo (IQFQElSize - 80 bytes with header ) 

(28) IOFDirlndex - directory index 

(30) IOFlAttrib - in-use bit-7, lock bit-0 

(31) IOFFIType - file type 

(32) IOFlUsrWds - user defined info (16 bytes) 

(48) IOFFINum - file number 

(52) IOFlStBlk - Start file block (0000 if none) 

(54) IOFILgLen - File logical length (EOF) 

(52) IOFIPyLen - File physical length in bytes. 

(62) IOFlRStBlk - Start file block, resource fork (0000 if none) 

(64) IOFIRLgLen - File logical length (EOF), resource fork 
(68) IOFIRPyLen - File physical length, resource fork 

(72) IOFICrDat - File creation date & time (32 bits in seconds) 

(76) IOFlMdDat - last modification date & time (32 bits in seconds) 

Equates specific to GetVolInfo,GetVolume,SetVolume,MountVol,UnmountVol, Eject 
(IOVQElSize - 64 bytes including header) 

(28) IOVolIndex - volume index number 

(30) IOVCrDate - creation date & time 

(34) IOVLsBkUp - last backup date & time 

(38) IOVAtrb - Volume attributes 

(40) IOVNmFls - # files in directory 

(42) IOVDirSt - start block of file dir 

(44) IOVBlLn - length of dir in blocks 

(46) IOVNmAlBlks - num blks (of alloc size) this dev 

(48) IOVAlBlkSiz - alloc blk byte size 

(52) IOVClpSiz - bytes to try to allocate at a time 

(56) IOAlBlSt - starting diskette (512-byte) block in block map 

(58) IOVNxtFNum - next free file number 

(62) IOVFrBlk - word of # free alloc blks for this vol 

Special Offsets for the Control and Status Core Routines 

(26) CSCode - a word for the control/ status code 

(28) CSParam - operation-defined parameters (20-bytes max) 


Most 1/0 processes may be performed asynchronously, thus allowing the user to 
more fully utilize the microprocessor: the user may specify a "completion 
routine” to be executed when the asynchronous 1/0 operation has been 

completed. Only the MountVol and UnmountVol routines must be executed 

synchronously: the completion routine field will be zeroed. 

A file is an array of bytes which may range in size from zero to one 
megabyte, limited however by the size of the volume it is on. Files may be 

read sequentially, or they may be random-accessed by using the position 

parameters of the Read core routine. Files are accessed via a reference 
number (Ref Num) assigned by the system. The Open core routine is called to 
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associate a reference number with a given filename. Thus a file must be 

opened^ before it can be read from or written to. There are two parts or 

forks to a file: the standard fork and a resource fork. The resource fork is 
opened for I/O with a special open call (OpenRF) documented in The File 

Management Core Routines. 

Some devices, however, need not be opened before they are accessed. The 
internal and external floppy drives are opened at system initialization time 
and left open. Other ROM -based drivers may also be opened at system 
tialization time (to be determined). The disk drives are accessed with 
RefNum $FFFB as drive numbers 1 (internal floppy) and 2 (external floppy). 

The current file system supports volume and file sizes up to 32 megabytes. 

A file is specified by "volume name:file name" and a file type byte. If no 

volume name is supplied, a default volume name is used. This default 

volume name may be changed by using the SetVolume core routine (one of the 
File System Core Routines) • Device driver names behave as if they were part 
of every volume name. 
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OPEN 


File and I/O Core Routine $AXdcT 
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OPEN is used to obtain a reference number for a given 
file, and to prepare that file for I/O. On entry, AO 
points to a parameter list. On exit, DO contains 
a result code. 


Parameter list format 


Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 


Result Flag : 2 -byte field 
Contains the I/O result flag. 

Result flag > 0: I/O not complete. Result flag ■ 0: 
I/O complete, no errors. Result flag < 0: I/O error 
detected . 


Filename : 4-byte pointer 

Specifies the name of the file to be opened. 


Drive Number : 2-byte field 

If non-zero and there is no volume prefix in the 
filename field, specifies which drive to use. 


Refnum : 2-byte result 

Contains the returned reference number . 
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OPEN 


File and I/O Core Routine $AX00 


File Type : 1-byte field 

Further specifies the file to be opened; typically 0, 
this field may be used to distinguish between 
different types of files (which have the same name) or 
different versions of the same file. 


Permissions : 1-byte field 

Specifies the type of I/O operation requested for 
the file: 

0: Both read and write, or whatever is allowed 

for this file. 1: Read only. If not allowed, 
an error is 

returned. 2: Write only. If not allowed, an 
error is 

returned. 3: Both read and write. If either mode 
is no 

allowed, an error is returned. 


Own Buffer : 4-byte pointer 

Pointer to a locked 522-byte buffer to be used for 
this file, or zero. If zero, the volume buffer will 
be used for this file; if non-zero, the file system 
will use this as a pointer to a buffer. The buffer 
should be word-aligned. 

All files (on the same volume) which are not opened 
with their own buffer will share a single 
one-block-long buffer among themselves and the file 
system. 


Comments 


For the file system, this call opens the standard part of the file for action: 
OpenRF is used to open the dual 'fork' of a file which is used for file label 
information and associated resources. Devices have no resource fork. 
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OPEN 


File and I/O Core Routine $AX00 


Errors 


-42 

$D6 

Too many files open 

-41 

$D7 

Memory full 

-36 

$DC 

Disk I/O error 

-35 

$DD 

No such volume 

-32 

$E0 

File not found 
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CLOSE 


File and I/O Core Routine $AX01 
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CLOSE is used to terminate I/O to a file. The file 
buffer is written out to disk, and the directory entry 
for the file updated as necessary. Further file 
operations using the refnum will fail after the file 
is closed. The disk driver will not close. On 

entry, AO points to a parameter list. On exit, DO 
contains a result code. 


Parameter list format 

Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 


Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Refnum ; 2-byte field 
Contains the reference number. 
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CLOSE 


File and I/O Core Routine $AX01 



Comments 


Errors 

-38 $DA File not open 

-36 $DC Disk I/O error 
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REAP File and i/o Core Routine $AX02 
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READ is used to perform a synchronous or 
asynchronous read operation from a file or 
device. It will not return to the user until the 
read operation is completed. On entry, AO points 
to a parameter list. On exit, DO contains a 
result code. 


Parameter list format 


Header : 12-byte field 

Maintained by the file and I/O system. 


Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 


Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Refnum : 2-byte field 
Contains the reference number. 


Data Buffer : 4-byte pointer 

Specifies the location of the data buffer. 
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File and I/O Core Routine $AX02 

Count : 4 -byte value 

A long word containing the number of bytes to be read 
Actual Read : 4 -byte value 

An output parameter indicating the number of bytes 
actually read. 


Position Mode : 2-byte field 

Contains the read termination or newline 
character information: Bits 8-15 = newline 
character, bit 7 * newline flag (1 = enable), bits 
0-1 * position information. 

Position Offset : 4 -byte value 

Contains a numeric parameter specifying the 
positioning operation to be done before the read is 
performed. If this longword and the previous 
parameter (bits 0-1 of Positon Mode) are both zero, 
no positioning will be done. 


Comments _ 

If a newline character is specified, the read will always be done 1 block at a 
time until the newline character is encountered or the byte count is 
satisfied . 

If a Read is requested with a position offset past the end of the file, an End 
of File error is returned. 


Errors 


-39 

$D9 

End of file 

-38 

$DA 

File not open 

-36 

$DC 

Disk I/O error 
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WRITE 


File and I/O Core Routine $AX03 
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WRITE is used . to perform a synchronous or 
asynchronous write operation to a file or 
device. On entry, AO points to a parameter 

list. On exit, DO contains a result code^ 



Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 


Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag * 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Refnurn : 2-byte field 
Contains the reference number. 


Data Buffer : 4-byte pointer 

Specifies the location of the data buffer. 
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WRITE 


File and I/O Core Routine $AX03 




Count: 4 -byte value 

A long word containing the number of bytes to be 
written. 


Actual Written : 4-byte value 

An output parameter indicating the number of bytes 
actually written. 

Position Mode : 2-byte field 

Contains the read termination or newline 
character information: Bits 8-15 ® newline 

character, bit 7 * newline flag (1 =* enable), bits 
0-1 ■ position information. 

Position Offset : 4 -byte value 

Contains a numeric parameter specifying the 
positioning operation to be done before the write 
is performed. If this longword and the previous 
parameter (bits 0-1 of Positon Mode) are both zero, 
no positioning will be done. 


Comments 

If the write operation extends past the physical end of file, the file will 
automatically be extended to accomodate the new data. 


-49 

$CF 

Memory dispose error 

-46 

$D2 

Volume locked 

-45 

$D3 

File locked 

-44 

$D4 

Diskette write protected 

-41 

$D7 

Memory full 

-38 

$DA 

File not open 

-36 

$DC 

Disk I/O error 

-34 

$DE 

Disk full 
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CONTROL File and I/O Core Routine $AX04 
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CONTROL is used to send device-specific 
information to a particular device (for example, 
setting the baud rate of an ACIA) . The format of 
the control information is individually defined 
for each device type. On entry, AO points to a 
parameter list. On exit, DO contains a result 
code. 


Parameter list format 


Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 


Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Refnum : 2-byte field 
Contains the reference number. 


Operation Code : 2-byte field 

Specifies the control operation to be performed. 


Operation-Specific Parameters : Variable length 

Specifies the operation-specific parameters 

and/or results. 


N 
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CONTROL 


File and I/O Core Routine $AXQ4 



Comments 


Errors (including device-specific errors) 


21 

$EB 

Unit empty 

■20 

$EC 

Bad unit number 

16 

$F0 

Control error 
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STATUS File and I/O Core Routine $AX05~ 
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STATUS is used to obtain status information about 
a particular file or device. For devices, the format 
of the returned status information is specific to 
the particular device type. For files, directory 
information is returned. On entry, AO points to a 
parameter list. On exit, DO contains a result code. 


Parameter list format 

Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4 -byte field 
Contains the I/O completion routine address. 

Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag >0: I/O not complete. 

Result flag =0: I/O complete, no errors. 
Result flag <0: I/O error detected. 

Refnum : 2-byte field 
Contains the reference number. 


Operation Code : 2-byte field 

Specifies the status operation to be performed. 


Operation-Specific Parameters : Variable length 

Specifies the operation-specific parameters 
and/or results. 
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STATUS 


File and I/O Core Routine $AX05 



Comments 


Errors (including device-specific errors) 


-21 

$EB 

Unit Empty 

-20 

$EC 

Bad unit number 

-17 

$EF 

Status error 
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FILE SYSTEM CORE ROUTINES $AX07 thru $AX18 $AX41 thru $AX45 


The File System Core Routines are used to manipulate files and 
information about files. All of the file system calls (except UnmountVol and 
MountVol) may be performed synchronously or asynchronously, according to the 
setting of bit 10 of the trap instruction, as explained in the Core Routine 
Invocation section, above. For asynchronous operations, there is a standard 
method of indicating when an operation has been completed. 

The file manager keeps a single directory with a limit of 255 bytes for any 
filename. The directory length is determined at diskette format time and may 
be made large enough to accomodate any number of files. 

The maximum length for a single file is the same as the volume length; the 
maximum size for a given volume is 32 megabytes. Disk blocks are allocated to 
a file in a fixed multiple of 512-bytes at at time (this multiple is also 
determined at diskette format time). 

There are two end-of-file pointers — logical EOF and physical EOF. The 
physical EOF is always greater than or equal to the logical EOF. The Allocate 
and SetEOF calls may be used to explicitly set the physical EOF, while Write 
will extend it as necessary. The physical EOF will always be a multiple of 
the allocation block size. 

A file name may be any length up to 255 characters. Unless there is some 
reason to place restrictions on names, filenames may be any sequence of 
printing alphanumeric characters — that is, there are no special reserved 
characters, either at the beginning of a filename, or anywhere within a 
filename. However, a colon within a name specifies that the first part of 
the name is a volume name, while the part following the colon is the name of 
the file on the specified volume. 

File names are stored exactly as they were originally specified. When a 
filename Is referenced, however, upper and lower case characters are treated 
as identical (the file system uses the system CmpString routine to check for 
sting matches) • 

There is a one-to-one correspondence between a mounted volume name and a drive 
number. The file and I/O system maintains a queue of disk drives in the 
system (associating drive numbers with driver reference numbers) which may be 
mounted and unmounted. The file system maintains a queue of mounted volumes: 
the number of volumes which may be mounted at any time is limited only by the 
number of drives in the system and the amount of system memory (each mounted 
drive requires approximately IK to 2K of space for the volume control block, 
volume buffer, and disk block map). 

File system calls may be grouped logically as volume-level calls, calls 
operating on unopened files, and calls operating on opened files: 
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Volume Level Calls 


GetVolInfo 
Get Volume 
SetVolume 
MountVolume 
Unmount Volume 
Eject 

FlushVolume 

Rename 


(get a volume's directory information) 

(get the name of the current default volume) 
(set the current default volume) 

(open a volume, allocating file system buffers) 
(close a volume , freeing file system buffers) 
(unmount a volume and eject the diskette) 

(flush all file system buffers for a volume) 
(rename a volume - also a file level call) 




File Level Calls for Unopened Files 


Open 

OpenRF 

Create 

Delete 

Rename 

GetFilelnfo 

SetFilelnfo 

SetFilLock 

RstFilLock 

SetFilType 


(open a file for action - see previous section) 
(open the resource fork of a file for action) 
(create a new file) 

(delete a file) 

(rename a file - also a volume level call) 

(get a file's directory information) 

(set a file's 8 user-definable directory words) 
(set a file's lock bit, a soft write protect) 
(reset a file's lock bit) 

(change a file's type byte) 




File Level Calls for Opened Files 


Close 

Read 

Write 

Allocate 

GetEOF 

SetEOF 

GetFilPos 

SetFilPos 

FlushFile 


(close a file - see previous section) 

(read from a file - see previous section) 

(write to a file - see previous section) 
(allocate contiguous diskette blocks to a file) 
(get a file's logical length) 

(set a file's logical length) 

(get the current position pointer for a file) 
(set the current position pointer for a file) 
(flush file buffers for one or all files) 


One final call, InitQueue, may be used to flush all queued file calls except 
the current one. 
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GETVOLINFO 


File and I/O Core Routine $AX07 
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GETVOLINFO is used to retrieve information about a 
currently mounted volume. On entry, AO points to a 
parameter list. On exit, DO contains a result code. 


Parameter list format 


Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 


Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Volume name : 4-byte pointer (result) 
The name of the volume is stored here. 


Drive Number : 2-byte field 

If non-zero and the volume index field is zero , 
specifies which drive. If both fields are zero, the 
default drive is used. Drive 1 is the internal drive, 
drive 2 is the external drive. 


Volume Index : 2-byte field 

Specifies the volume queue index for the volume to be 
investigated. If zero, the drive number field is 
used; if negative, the volname is used. 
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GETVOLINFO 


File and I/O Core Routine $AX07 
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FREE 

ALLOCATION 
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64 


Creation Date : 4-byte value 

Contains the volume creation date and time in seconds. 
Modification Date : 4 -byte value 

Contains the volume modification date and time in 
seconds . 

Volume Attributes : 2-byte value 

Bit 15 =* lock bit; Bit 7 ® hard write protect bit. 
Number of Files : 2-byte value 

Contains the number of files in the volume directory. 

Directory Start Block : 2-byte value 

Contains the directory start 512-byte block number. 


Directory Block Length : 2 -byte value 

Contains the number of 512-byte blocks in the volume 
file directory. 


Allocation Blocks : 2 -byte value 

Contains the total number of allocation-size blocks on 
this diskette (used and unused) . 






Allocation Block Byte Size : 4-byte value 

Contains the number of bytes in an allocation block 
(must be a multiple of 512). 


February 28, 1983 


CONFIDENTIAL 


.os 


Macintosh OS 


Core Routines — File and I/O 3*2-5 


GETVOLINFO 


File and I/O Core Routine $AX07 


Minimum Allocation Size : 4-byte value 

Contains the minimum number of contiguous bytes the 
file system will search for before allocating any 
blocks to a file. 


Allocation Blocks Start Block : 2 -byte value 

Contains the 512-byte block number where the 
allocation blocks start. 


Next Available File Number : 4 -byte value 

Contains the next longword filenumber which will be 
assigned to the next file created. 

Free Allocation Blocks : 2 -byte value 

Contains the number of free allocation-size blocks on 
this volume. 


Comments 


GetVolInfo is particularly useful when you do not know the name of the 
volume that is currently installed in a particular disk drive. 


Errors 


-36 

$DC 

Disk I/O error 

-35 

$DD 

No such volume 

-53 


Volume not on-line error 
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GETVOLUME 


File and I/O Core Routine $AX14 
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GETVOLUME is used to obtain the name of the 
current default volume. On entry, AO points to a 
parameter list. On exit, DO contains a result code. 


Parameter list format 

Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4 -byte field 
Contains the I/O completion routine address. 

Result Flag : 2 -byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Volume name : 4-byte pointer (result) 

The name of the default volume is stored here (if nil, 
only the drive number is returned) . 


Drive Number : 2-byte field 

The drive number of the default drive is returned in 
this field. 
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GETVOLUME 


File and I/O Core Routine $AX14 


Comments 




Errors 


-56 $xx No such drive (no default volume) 
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SETVOLUME 


File and I/O Core Routine $AX15 
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SETVOLUME is used to set the current default volume. 
On entry, AO points to a parameter list. On 
exit, DO contains a result code. 


Parameter list format 


Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address ; 4-byte field 
Contains the I/O completion routine address. 


Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Volume name: 4-byte pointer (result) 

This field is the pointer to the name of the volume to 
be made the default. 


Drive Number : 2-byte field 

If the volume name field is nil, this specifies the 
drive number of the volume to become the default. 
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SETVOLUME 


File and I/O Core Routine $AX15 


Comments 


Errors 


-35 $DD No such volume 

-56 $xx No such drive 
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MOUNTVOLUME 


File and I/O Core Routine $A00F 
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MOUNTVOLUME is used to read in a volume's master 
directory block, and allocate file system data 
structures to handle that volume. On entry, AO 
points to a parameter list. On exit, DO contains a 
result code. This call is always executed 
synchronously since memory has to be allocated for the 
data structures. 


Parameter list format 

Header : 12-byte field 

Maintained by the file and I/O system. 




Completion Routine Address ; 4-byte field 
Contains the I/O completion routine address. 


Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Drive Number : 2-byte field 


Specifies the number of the drive to be mounted. 
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MOUNTVOLUME 


File and I/O Core Routine $A00F 


Comments 


This routine will be typically called when a disk in place event occurs. 


Errors 


-56 

$xx 

No such drive 

-55 

$xx 

Volume is already mounted. 

-50 

$xx 

Error in user parameter list (no drive specified) 

-XX 

$xx 

Memory full error 

-57 

$xx 

Diskette does not have a Macintosh directory 

-60 

$xx 

Master Directory Block is inconsistent 
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UNMOUNTV OLUME 


File and I/O Core Routine $A00E 


UNMOUNTVO LUME is used to unmount a volume: all files 


or 

i 

i 

HEADER 

1 on the volume are closed, the buffers written out, and 

I memory for the volume buffer and data structures is 

1 deallocated. This call is always executed 

121“ 

1 


synchronously. On entry, AO points to a 
list. On exit, DO contains a result code. 

parameter 

161“ 
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IORESULT 

(RESULT) 

Parameter list format 


18 1 
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1 

1 

VOLUME NAME 
(POINTER) 

1 Header: 12-byte field 


22 f 
1 

1 

l_ 

DRIVE 

NUMBER 

' Maintained by the file and I/O system. 

1 Completion Routine Address: 4-byte field 



Contains the I/O completion routine address. 


Result Flag : 2 -byte field 

Contains the I/O result flag. 

Result flag >0: I/O not complete. 

Result flag ■ 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Volume name : 4-byte pointer (result) 

This field is the pointer to the name of the volume to 
be unmounted. 


Drive Number : 2-byte field 

If the volume name field is nil, this specifies the 
drive number of the volume to be unmounted. 
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UNMOUNTVOLUME 


File and I/O Core Routine $A00E 


Comments 


Volumes may be unmounted and mounted to minimize the amount of memory the file 
system uses. If the volume to be unmounted is on a diskette which should be 
ejected , the Eject call should be used instead . 


Errors 



-35 

$DD 

No such volume 


-56 

$xx 

No such drive 


-xx 

$xx 

Disk error 
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EJECT 


File and I/O Core Routine $AX17 
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EJECT is used to unmount a volume (it calls 
UNMOUNTVO LUME ) and eject the diskette on which the 
volume resides. The unmount is always done 

synchronously, while the eject may be asynchronous. 
The diskette is ejected by a control call to the 
appropriate disk driver. On entry, AO points to a 
parameter list. On exit, DO contains a result code. 


Parameter list format 

Header: 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4 -byte field 
Contains the I/O completion routine address. 




Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag - 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Volume name: 4-byte pointer (result) 

This field is the pointer to the name of the volume to 
be Unmounted and Ejected. 


Drive Number : 2-byte field 

If the volume name field is nil, this specifies the 
drive number of the volume to be Unmounted and 
Ejected. 
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EJECT 


File and I/O Core Routine $AX17 


Comments 


Errors 


-35 

$DD 

No such volume 

-56 

$xx 

No such drive 

-XX 

$xx 

Disk error 
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File and I/O Core Routine SAX13 
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FLUSHVOLUME is used to flush all file system buffers 
for a volume and files on that volume. After a 
FLUSHVOLUME call, the file system data structures in 
memory will be consistent with those on the diskette. 
On entry, AO points to a parameter list. On 
exit, DO contains a result code. 


Parameter list format 

Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4 -byte field 
Contains the I/O completion routine address. 

Result Flag: 2-byte field 


Contains the I/O result flag. 


Result flag > 0: I/O not complete. 

Result flag ■ 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 




Volume name: 4-byte pointer (result) 

This field is the pointer to the name of the volume to 
be flushed. ^ 


Drive Number : 2-byte field 

If the volume name field is nil, this specifies the 
drive number of the volume to be flushed. 
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FLUSHVOLUME File and I/O Core Routine $AX13 


Comments 


FlushVolume may be called automatically by the system on a regular basis 
(e.g., before the drive is powered down). 


Errors 




-35 $DD No such volume 

-56 $xx No such drive 
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INITQUEUE File and I/O Core Routine $AX22 

INITQUEUE is used to clear the file system queue. 
INITQUEUE has no parameters, and is always executed 
immediately. Any currently executing request is 
allowed to continue . 


Comments 


The file system queues up asynchronous calls. Initqueue clears out any calls 
in the queue . 

InitQueue can be used if an error occurs in a call, and the user no 
longer wishes the other calls in the queue to be executed. 




Errors 

none. 






February 28 


1983 


CONFIDENTIAL 


3p2.os 


Macintosh OS 


Core Routines — File and I/O 3.2-19 







16 

18 

22 

24 

26 

27 


01 

1 

1 

HEADER 

! 

21“ 

' 1 

1 

COMPLETION | 

1 

ROUTINE | 

1 

1 

ADDRESS | 

1 

’1 1 

1 IORESULT | 

1 1 

II 

1 

FILENAME | 


(POINTER) | 

1 


1 

DRIVE | 


NUMBER | 

1 


FILE TYPE 


CREATE is used to create a file with a specified 
filename and filetype. On entry, AO points to a 
parameter list. On exit, DO contains a result code. 


Parameter list format 

Header : 12-byte field 
Maintained by the file system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 

Result Flag ; 2-byte field 

Contains the. I/O result flag. 

Result flag >0: I/O not complete. 

Result flag ■ 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 




Filename : 4-byte pointer 

Contains a pointer to the name of the file. The name 
may have a volume prefix, in which case the file is 
created on the specified volume. If there is no 
volume prefix, and the drive number field is zero, the 
file will be created on the default drive. 

Drive Number : 2-byte field 

If non-zero and the filename has no volume prefix 
this specifies the drive/volume on which the file is 

1 ° e crea ted. if neither volume name or drive number 
are given, the default volume will be used. 
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CREATE 


File and I/O Core Routine $AX08 




Filetype : 1-byte field 

Specifies the type byte for the file to be created* 


Comments 

Creates a file with zero length regular and resource forks; the file 
modification and creation dates are initialized from the system seconds time 
count. The user-defined information is all zeroed and the entry is marked 
unlocked • 




Errors 


-48 

$D0 

Duplicate filename 

-46 

$D2 

Volume locked 

-44 

$D4 

Diskette write protected 

-36 

$DC 

Disk I/O error 

-35 

$DD 

No such volume 

-33 

-53 

$DF 

Directory full 

Volume not on-line error 
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DELETE 


File and I/O Core Routine $AX09 


DELETE is used to delete a file with a specified 
filename. Files that are write-restricted or in use 


01 

1 

1 

HEADER 

(open) may not be deleted. On entry, AO points to 
a parameter list. On exit, DO contains a result 
code. 
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Parameter list format 

16| 
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IORESULT 
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181 


Maintained by the file system. 

1 

FILENAME 


1 

1 

(POINTER) 

Completion Routine Address: 4-byte field 

22| 

1 

DRIVE 

Contains the I/O completion routine address. 

1 

1 

NUMBER | 
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24| 
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-J 

.1 

. / Result Flag: 2-byte field 

26 1 

1 

1 

FILE TYPE | 

Contains the I/O result flag. 

1 

1 

Result flag > 0: I/O not complete. 


27 Result flag =0: I/O complete, no errors. 


Result flag < 0: I/O error detected. 


Filename : 4-byte pointer 

The name of the file to be deleted is stored here. 


Drive Number: 2-byte field 

If non-zero and the filename has no volume prefix, 
this specifies the drive/volume on which the file to 
be deleted resides. If neither volume name or drive 
number are given, the default volume will be used. 
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Filetype : 1-byte field 

Specifies the type byte for the file to be deleted: 
both the name and type must match before the file will 
be deleted. 


Comments 


Delete removes a file from the file directory and marks all blocks allocated 
to that file free in the volume block map; the file's blocks on the disk are 
not zeroed, however. 


Errors 


-47 

$D1 

File busy — > 


-46 

$D2 

Volume locked 

T •• * 

-45 

$D3 

File locked 


-44 

$D4 

Diskette write protected 


-36 

$DC 

Disk I/O error 


-35 

$DD 

No such volume 


-32 

$E0 

File not found 
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OPENRF is used to obtain a reference number for a 
given f lie, and to prepare the resource fork of that 
file for I/O. On entry, AO points to a parameter 
list. On exit, DO contains a result code. 


Parameter list format 


Header : 12-byte field 
Maintained by the file system. 


Compl etion Routing Address.: 4-byte field 
Contains the I/O completion routine address. 


Result Flag : 2 -byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag =0: I/O complete, no errors. 
Result flag <0: I/O error detected. 


Filename : 4-byte pointer 


Specifies the name of the file to be opened. 


Drive Number : 2 -byte field 


If non-zero and there is no volume prefix in 
filename field, specifies which drive to use. 
neither volume name or drive number are given 
default volume will be used. * 


the 

If 

the 


Refnum : 2-byte result 


Contains the returned reference number. 
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Filetype : 1-byte field 

Further specifies the file to be opened; typically 0, 
this field may be used to distinguish between 
different types of files (which have the same name) or 
different versions of the same file. 


Permissions : 1-byte field 

Specifies the type of I/O operation requested for 
the file: 

0: Both read and write, or whatever is allowed 

for this file. 1: Read only. If not allowed, 
an error is 

returned. 2: Write only. If not allowed, an 
error is 

returned. 3: Both read and write. If either mode 
is not 

allowed, an error is returned. 


Own Buffer : 4-byte pointer 

Pointer to a locked 522-byte buffer to be used for 
this file, or zero. If zero, the volume buffer will 
be used for this file; if non-zero, the file system 
will use this as a pointer to a buffer. The buffer 
should be word-aligned. 

All files (on the same volume) which are not opened 
with their own buffer will share a single 
one— block— long buffer among themselves and the file 
system. 
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Comment s 


When^a file is opened (either by Open or OpenRF) , the file system locates that 
file s entry in the file directory and copies the pertinent information into a 
f* 1 !.! 781 " memor y structure called a File Control Block. The file system has 
12 File Control Blocks to share among all file and volumes: this limits the 
number of open files at any one time to 12. 

A file may be opened multiple times to share it among several processes: each 
pen 1 return a unique refnum. At any one time, however, a file fork may 
only be opened once with write permissions (i.e., a file's regular and 
resource forks may be opened for read/write and at the same time for read-only 
a number of times, limited only by the maximum number of files which may be 
open at any one time. Each Open will have a unique refnum and current file 
pos t on, but the logical and physical lengths of the resource and regular 
forks are kept the same for all File Control Blocks for that fork. 


Errors 


-42 

$D6 

Too many files open 

-36 

$DC 

Disk I/O error 

-35 

$DD 

No such volume 

-32 

$E0 

File not found 

-49 

$<-' 

File already open with ' 

-61 

$'&<■ ; 

Write Permissions Error 
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01 
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HEADER 1 
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COMPLETION 1 

1 

ROUTINE I 

1 

1 

ADDRESS 1 
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IORESULT 1 
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FILENAME I 
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1 

(POINTER) I 
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DRIVE 1 
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1 

NUMBER I 
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FILE TYPE I 
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i 

NEW NAME 1 

1 

1 

(POINTER) | 

1 
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RENAME is used to change the name of a file or a 
volume from FileName to NewName. On entry, AO 
points to a parameter list* On exit, DO contains a 
result code. 


Parameter list format 


Header : 12-byte field 
Maintained by the file system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 


Result Flag : 2 -byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag ■ 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Filename : 4 -byte pointer 

Specifies the old name of the file or volume being 
renamed. The pointer specifies the location of the old 
name. 


Drive Number : 2-byte field 

If non-zero and the filename has no volume prefix, 
this specifies the drive/volume on which the file to 
be renamed resides. If neither volume prefix nor 
drive number are given, the default volume will be 
used . 
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Filetype : 1-byte field 

Specifies the type byte for the file to be renamed: 
both the name and type must match before the file will 
be renamed. For volume renaming, this field is 
ignored . 

New Name : 4-byte pointer 

Specifies the new name of the file or volume 
being renamed. The pointer specifies the location of 
the new name. 


Comments 


Rename is slow since it must search through the file directory twice: once to 
verify that the target name does not already exist, and once to locate the 
file directory entry; additionally, if the new name is long enough that the 
file entry no longer fits on the same directory block, the directory must be 
further searched for a block with enough space. 

The file type byte is kept the same (use the SetFilType command to change the 
type field). 


Errors 


-48 

$D0 

Duplicate filename 

-46 

$D2 

Volume locked 

-45 

$D3 

File locked 

-44 

$D4 

Diskette write protected 

-37 

$DB 

Bad filename 

-36 

$DC 

Disk I/O error 

-35 

$DD 

No such volume 

-33 

$DF 

Directory full 

-32 

$E0 

File not found 
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GETFILEINFO is used to retrieve information about 

0 

12 

16 

18 

22 

24 
26 

27 

28 

30 
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FILE TYPE 


DIRECTORY 

INDEX 


ATTRIBUTES 


FILE TYPE 


a particular file. If the directory index is greater 
than zero, the filename parameter is ignored, and 
information is returned about the Nth file, as 
specified by the index. If the index is zero, the 
filename parameter is used. On entry, AO points to 
a parameter list. On exit, DO contains a result 
code. 


Parameter list format 

Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 

Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag ■ 0: I/O complete, no errors. 

Result flag < 0: I/O error detected. 

Filename: 4-byte pointer 

Specifies the name of the file being 
investigated. The pointer specifies the 

location of the filename. 




Drive Number : 2-byte field 

If non-zero and the filename has no volume prefix, 
this specifies the drive/ volume on which the file to 
be found resides. If neither volume prefix nor drive 
number are given, the default volume will be used. 
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Flletype: 1-byte field 


32| 

1 

1 

1 

1 

USER-DEFINED I 
WORDS | 

1 

Specifies the type byte for the file to be found: both 
the name and type must match, unless searching by 
index. 

481 

1 

1 

1 

FILE NUMBER | 

1 

Directory Index: 2-byte field 

52|" 

f 

1 

START BLOCK | 

1 

Specifies the directory index for the file to be 
investigated. If zero, the file name field is used. 

54| 

1 

1 

1 

1 

LOGICAL BYTE I 
LENGTH | 

1 

File Attributes: 1-byte value 

58| 

1 

! 

1 

1 

PHYSICAL BYTE | 
LENGTH | 

1 

Bit 0 “ lock bit (1 if locked) Bit 7 =■ in use 

bit (file open) 

62| 

1 

1 

1 

'1 

RESOURCE | 

START BLOCK | 

1 

File Type: 1 byte value 

File type field from the directory entry. 

64| 

1 

1 

1 

1 

1 

RESOURCE | 

LOGICAL BYTE | 
LENGTH | 

1 

User Defined Words: 16-byte field 

Defined by the user and stored in the directory. 

68| 

1 

1 

1 

1 

1 

RESOURCE | 

PHYSICAL BYTE | 
LENGTH | 

1 

File Number: 4-byte value 

4 -byte number unique to this file on this volume. 

721 

1 

1 

1 

CREATE DATE | 

1 

File Start Block: 2-byte value 

761 

1 

1 

1 

MOD DATE | 

1 

Starting allocation block for the regular fork of this 
file: 0 if the fork is of length 0. 


80 


File Logical Length : 4 -byte value 

Logical byte length of the regular fork of the file. 
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File Physical Length : 4 -byte value 

Physical byte length of the regular fork of the file: 
always a multiple of the allocation byte size « 

File Resource Start Block : 2 -byte value 

Starting allocation block for the resource fork of 
this file: 0 if the fork is of length 0. 

File Resource Logical Length : 4 -byte value 

Logical byte length of the resource fork of the file. 

File Resource Physical Length : 4-byte value 

Physical byte length of the resource fork of the file: 
always a multiple of the allocation byte size. 

Creation Date : 4-byte value 

Contains the file creation date and time in 

seconds . 

Modification Date : 4 -byte value 

Contains the file modification date and time in 

seconds. 
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Comments 


GetFilelnfo is particularly useful when you do not know the name of the files 
on a volume. 




Errors 


-36 

$DC 

Disk I/O 

error 

-35 

$DD 

No such volume 

-32 

$E0 

File not 

found 
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SETFILEINFO is used to set information 
associated with a particular file. On entry, AO 
points to a parameter list. On exit, DO 

contains a result code. 


Parameter list format 


Header : 12-byte field 

Maintained by the file and I/O system. 


Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 


Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag ■ 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Filename : 4 -byte pointer 

Specifies the name of the file being 
investigated. The pointer specifies the 
location of the filename. 


Drive Number : 2-byte field 

If non-zero and the filename has no volume prefix, 
this specifies the drive/volume on which the file to 
be found resides. If neither volume prefix nor drive 
number are given, the default volume will be used. 
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Filetype : 1-byte field 

Specifies the type byte for the file to be found: both 
the name and type must match. 

User Defined Words : 16-byte field 

These 16 bytes are stored in the directory entry of 
the specified file. 


Comments 


Note that the Creation Date, Modification Date, file start blocks, logical 
and physical lengths, and system file number parameter may not be set by the 
user. These are set only by the operating system. The file type field is set 
with the SetFilType command, and the lock bit is set and reset with the 
SetFilLock and RstFilLock commands. 

If only certain bytes are to be changed, the GetFilelnfo command should be 
issued first, the desired bytes changed, and then the SetFilelnfo command 
given. 


Errors 


-46 

$D2 

Volume locked 

-45 

$D3 

File locked 

-44 

$D4 

Diskette write protected 

-36 

$DC 

Disk I/O error 

-35 

$DD 

No such volume 

-32 

$E0 

File not found 
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Parameter list format ___ 

Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 

Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 
Result flag < 0: 1/0 error detected. 


Filename : 4-byte pointer 

The name of the file to be locked is stored here. 


Drive Number : 2-byte field 

If non-zero and the filename has no volume prefix, 
this specifies the drive/volume on which the file to 
be locked resides. If neither volume name or drive 
number are given, the default volume will be used. 
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Filetype : 1-byte field 

Specifies the type byte for the file to be locked: 
both the name and type must match before the file can 
be found. 


Comments 


Issuing this command will not prevent writes to the file if it is already 
opned with write permission. 


Errors 


-46 

$D2 

Volume locked 

-44 

$D4 

Diskette write protected 

-36 

$DC 

Disk I/O error 

-35 

$DD 

No such volume 

-32 

$E0 

File not found 
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File and I/O Core Routine $AX42 
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RSTFILLOCK is used to unlock a specified file. Files 
on volumes that are write-restricted or locked may not 
be unlocked. On entry, AO points to a parameter 
list. On exit, DO contains a result code. 


Parameter list format 


Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 


Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Filename : 4-byte pointer 

The name of the file to be unlocked is stored here. 


Drive Number : 2-byte field 

If non-zero and the filename has no volume prefix, 
this specifies the drive/volume on which the file to 
be unlocked resides. If neither volume name or drive 
number are given, the default volume will be used. 
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Filetype : 1-byte field 

Specifies the type byte for the file to be unlocked: 
both the name and type must match before the file can 
be found. 


Comments 


Errors 


-46 

$D2 

Volume locked 

-44 

$D4 

Diskette write protected 

-36 

$DC 

Disk I/O error 

-35 

$DD 

No such volume 

-32 

$E0 

File not found 
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SETFILTYPE is used to set the type byte of a file. 
Files that are write-restricted or on volumes which 
are locked or write-protected may not be changed. On 
entry, AO points to a parameter list. On 

exit, DO contains a result code. 


Parameter list format 

Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 

Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag » 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 

Filename: 4-byte pointer 


The name of the file to be retyped is stored here. 




Drive Number : 2-byte field 

If non-zero and the filename has no volume prefix, 
this specifies the drive/ volume on which the file to 
be retyped resides. If neither volume name or drive 
number are given, the default volume will be used. 
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Filetype : 1-byte field 

Specifies the type byte for the file to be retyped: 
both the name and type must match before the file can 
be found. 

NewType : 1-byte field 

Specifies the new type field for the file. 


Comments 


SetFilType is slow since it must search through the file directory twice: 
once to verify that the target name/ type does not already exist, and once to 
locate the file directory entry. This command is similar to rename. 


Errors 


-48 

$D0 

Duplicate filename 

-46 

$D2 

Volume locked 

-45 

$D3 

File locked 

-44 

$D4 

Diskette write protected 

-37 

$DB 

Bad filename 

-36 

$DC 

Disk I/O error 

-35 

$DD 

No such volume 

-33 

$DF 

Directory full 

-32 

$E0 

File not found 
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ALLOCATE File System Core Routine $AX1Q 

ALLOCATE is used to allocate a specified number of 
bytes to a file. These are in addition to any 
blocks the file already has. On entry, AO points 
to a parameter list. On exit, DO contains a 
result code. 


Parameter list format 

Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 

Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 

Result flag < 0: I/O error detected. 

Ref num : 2-byte field 
Contains the reference number. 

Count Requested : 4-byte field 

Specifies the number of bytes to be added on to the 
file's existing allocation. 
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44 


Actual Count : 4-byte field 

An output parameter indicating the number of 
additional bytes actually allocated to this file. 
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Comments 


This routine is provided to allow a large contiguous block of disk space to be 
allocated to a file which is to be gradually filled up, preventing 
fragmentation of the file over many tracks. To recover unused space, a SetEOF 
call should be done* When a file is to be written all at once, this call is 
unnecessary. 

Note that the count is in bytes (not blocks, as in the Lisa operating 
system) . The number of bytes to be added is always rounded up to the nearest 
multiple of the allocation block size* 

If there are not enough empty blocks on the diskette to satisfy the total 
request, this routine will allocate as many blocks as it can (the rest of the 
diskette) and report disk full. 


Errors 


-38 

$DA 

File not open 

-46 

$D2 

Volume locked 

-45 

$D3 

File locked 

-44 

$D4 

Diskette write protected 

-36 

$DC 

Disk I/O error 

-34 

$DE 

Disk Full 
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GETEOF is used to find out the current logical byte 
length of a file. On entry, AO points to a parameter 
list. On exit, DO contains a result code. 


Parameter list format 


Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4-byce field 
Contains the I/O completion routine address. 


Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Refnum: 2-byte field 


Contains the reference number. 


Logical Byte Length : 4 -byte value 

Contains the current file logical length in bytes. 
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Comments 




Errors 


-38 $DA 

-36 $DC 


File not open 
Disk I/O error 
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SETEOF is used to change the current logical byte 
length of a file. On entry, AO points to a parameter 
list. On exit, DO contains a result code. 


Parameter list format 

Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address ; 4-byte field 
Contains the I/O completion routine address. 

Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 

Refnum: 2-byte field 


Contains the reference number. 


Logical Byte Length : 4-byte field 

Contains the desired file logical length in bytes. 
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Comments 


The physical length of the file will be extended as necessary; if the logical 
length is set to less than the current physical length, any unneeded physical 
blocks will be deallocated. 


Errors 


-38 

$DA 

File not open 

-36 

$DC 

Disk I/O error 

-46 

$D2 

Volume locked 

-45 

$D3 

File locked 

-44 

$D4 

Diskette write protected 

-36 

$DC 

Disk I/O error 

-34 

$DE 

Disk full 
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GETFILPOS 


File and I/O Core Routine $AX18 
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GETFILPOS is used to obtain the current file position 
pointer for an opened file. This routine actually 
just calls read with a zero positioning mode and zero 
byte count. On entry, AO points to a parameter list. 
On exit, DO contains a result code. 


Parameter list format 

Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 

Result Flag ; 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 

Refnum : 2-byte field 
Contains the reference number. 

Count : 4-byte value 

This field is zeroed by this routine. 

Actual Read : 4 -byte value 

This field is zeroed by this routine. 
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GETFILPOS File and I/O Core Routine $AX18 

Position Mode : 2-byte field 

The positioning byte in this field is zeroed by this 
routine. 

File Position : 4 -byte value 

The current file position is returned in this field. 


Comments 


This routine is provided for convenience; a read of zero bytes and no 
positioning specified will accomplish the same result. 


Errors 


-39 

$D9 

End of file 

-38 

$DA 

File not open 

-36 

$DC 

Disk I/O error 
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SETF ILPOS File and I/O Core Routine $AX44 __ 

SETFILPOS is used to set the current file position 
pointer for an opened file. This routine actually 
just calls read with the specified positioning mode, 
position offset, and zero byte count. On entry, AO 
points to a parameter list. On exit, DO contains a 
result code. 


Parameter list format 

Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address : 4-byte field 
Contains the I/O completion routine address. 

Result Flag : 2-byte field 

Contains the I/O result flag. 

Result flag > 0: I/O not complete. 

Result flag = 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 

Refnum : 2-byte field 
Contains the reference number. 

Count: 4 -byte value 

This field is zeroed by this routine. 

Actual Read : 4 -byte value 

This field is zeroed by this routine. 
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SETFILPOS 


File and I/O Core Routine $AX44 


Position Mode: 2-byte field 

Bits 0-1 contain positioning information. 

Position Offset : 4-byte field 

This field, interpreted according to the postioning 
mode, specifies the new file position. 


Comments 


This routine is provided for convenience; a read of zero bytes with the 
desired positioning specified will accomplish the same result. If the 
position specifies past the current logical end -of -file, the position is set 
to the end-of-file and an end-of-file error is reported. 


Errors 


-40 

$ 

Tried to position to before start of file 

-39 

$D9 

End of file 

-38 

$DA 

File not open 

-36 

$DC 

Disk I/O error 
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FLUSHFILE 


File System Core Routine $AX45 
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FLUSHFILE is used to flush the file buffer of any data 
and to update the file's directory entry with any 
changes. On entry, AO points to a parameter list. On 
exit, DO contains a result code. 


Parameter list format 

Header : 12-byte field 

Maintained by the file and I/O system. 

Completion Routine Address ; 4-byte field 
Contains the I/O completion routine address. 

Result Flag: 2-byte field 


Contains the I/O result flag. 


Result flag > 0: I/O not complete. 

Result flag =* 0: I/O complete, no errors. 
Result flag < 0: I/O error detected. 


Refnum : 2-byte field 
Contains the reference number. 


Comments 


A refnum of zero no longer flushes all files on the volume: use FlushVol for 
this. The directory entry is updated in the memory buffer (after the correct 
directory block is read in) but this block is not explicitly written out (for 
performance reasons) - FlushVolume will, however, write out all buffers to 
disk. 
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FLUSHFILE 


File System Core Routine $AX45 


Errors 


-38 

$DA 

File 

not 

open 

-36 

$DC 

Disk 

I/O 

error 

-32 

$E0 

File 

not 

found error (trouble!) 
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ADDDRIVE File System Core Routine $AX4E 

AddDrive input : DO.L - high-order word = drive number 
low-order word =* driver refnum 
AO.L - pointer to a 10-byte block, of 
non-relocatable memory to be 
used for the queue element. 


Calling sequence: 

MOVE.W 

SWAP 

MOVE.W 

LEA 

AddDrive 


#driveNum,DO 

DO 

#drvrRefnum ,D0 
MemlOBytes,AO 


Comments 




This routine is used to add another disk drive to the OS drive queue. 
This queue normally contains only 1 or 2 elements (internal and 
external disk drives), but may be expanded as needed. Drive numbers 
are unique in the system: this queue associates a drive (drive number) 
with the refNum of the I/O driver which supports this drive. Once a 
drive has been entered into the queue, a diskette in the drive may be 
mounted (via MountVolume) and files on that diskette accessed via file 
system calls. 


Errors 
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The OS Event Manager 

The Event Manager core routines manipulate events on the system 
event queue* These consist of functions such as adding and retrieving events 
from the system event queue, polling for available events, and removing 
events from the queue. The system queue is initialized to contain 30 22-byte 
elements. 

(ToolEvents contain the higher-level ToolBox event handling calls EventAvail 
and GetNextEvent : these will be documented separately with other ToolBox 
documentation, although some ToolEvents-def ined events are briefly covered 
here. ToolEvents makes calls to OSEvent Avail and GetOSEvent, adding Activate 
and Update events, and supports journaling. Most application programs will 
just make calls to ToolEvents. ) 

Four routines are associated with the event manager: Post Event, OSEvent Avail , 
GetOSEvent, and FlushEvents. PostEvent may be called from an Interrupt 
or completion routine; all other routines in the event manager must be called 
from the main thread of execution. Additionally, the system event mask may 
be read and set via the OS routines GetSysParam and SetSysParam. 

The Event Manager manages its own private buffer to get storage for the event 
queueing elements. It does this because PostEvent runs at interrupt level and 
thus cannot call the standard storage allocater. 


Events 

The Macintosh operating system uses the metaphor of an "event" to report 
to user programs the occurance of keyboard keypresses, mouse button state 
changes, and other relatively slow and irregular things which the system 
detects and the user program is interested in. Faster input/output, such 
as receipt of a character on one of the serial port , is handled via the 
"I/O driver” model in the I/O and File subsystems. 

Event Mask, Event Number 

Events are posted and selected subject to event masks; an event mask is a word- 
long bitmap of all possible events: a 1 in the bit position of an event enables 
that event. Possible events by event number, bit position in event mask, 
and name are: 


0 

$0001 

Null Event 

1 

$0002 

Mouse button down 

2 

$0004 

Mouse button up 

3 

$0008 

Key down 

4 

$0010 

Key up 

5 

$0020 

Auto -key 

6 

$0040 

Update event 

7 

$0080 

Disk Inserted 



8 

$0100 

Activate/Deactivate event 

9 

$0200 

Abort event 

10 

$0400 

Network event 

11 

$0800 

10 Driver event 

12 

$1000 

application defined 

13 

$2000 

application defined 

14 

$4000 

application defined 

15 

$8000 

application defined 


Event Queue Element, Event Record 

The basic data structure for events is a 22-byte buffer called an EVENT QUEUE 
ELEMENT, in which events are buffered by the Event Manager. Events are 
communicated to users via EVENT RECORDS, which are structured like event queue 
elements, minus the six-byte queue link and type fields. The SYSTEM EVENT 
BUFFER has room enough for 30 event queue elements. 

Event Queue Element: 

(0) Queue link to next element, zero for last element (32-bit) 

(4) Queue type field, set to $0004 (16-bit) 

(6) Event Record (16-byte) 

Event Record: 

(0) Event Number (16-bit) 

(2) Event-defined message (32 -bit) 

(6) TICKS value when event occurred (32-bit) (TICKS is a 32-bit 
variable which is incremented every 1/60 second) 

(10) Mouse position when event occurred (32-bit) 

(14) Meta-key flags (8-bit) as follows (bit*l when key is down): 

bit 7-4: undefined 
3: option key 
2: alpha-lock key 
^ 1: shift key 
0: command 

(15) Mouse button state (8-bit): 

bit 7: down^OjUp**! 

6-0: undefined (toolevents uses bits 0-1 to distinguish 
activate from deactivate, and sys-appl change). 

Event-defined messages are as follows (including ToolEvents-def ined events): 


Null Event 

Mouse button down 

Mouse button up 

Key down 

Key up 

Auto -key 

Disk Inserted 

Update event 

Activate/Deactivate 


none (0) 
none (0) 
none (0) 

byte0=*bytel=0,byte2=raw keycode,byte3=ASCII code 
byte0=bytel a »0,byte2 aa raw keycode,byte3=ASCII code 
byte0=*bytel=0,byte2 sa raw keycode,byte3»ASCII code 
drive number : 1 internal , 2 external 
32-bit windowPtr of window to be updated 
3 2 -bit windowPtr 


Events are generally posted as they occur and are self-explanatory; 



some notable exceptions are the null event and auto-key events. 

For this discussion, events will be classified into standard events (1-4 and 7-8), 
auto-key events, and the null event. An event is available 
only when it is enabled by the user-specified event mask. 

The null event is returned by OSEvent Avail and GetOSEvent when no standard or 
auto-key events are available. Null events are always enabled 
(i.e., generation of null events is not subject to a mask), and they are never 
posted into the system event queue. 

Auto-key events are posted into the event queue by OSEventAvail when there are 
no standard events available, there is a repeatable key down, the repeat time 
thresholds have been satisfied, and auto-key events are enabled by both the 
user-specified mask and the system event mask. The posted auto-key is returned 
like a standard event (and dequeued if posted by a GetOSEvent call to 
OSEventAvail) . 

The null event returns the current state of the mouse 

button, mouse position, keyboard meta-keys, and the current value of TICKS. 


Routine: Post Event 

Arguments: AO (input) 

DO (input) 
DO (output) 


event number (16-bit) 

event message (32-bit) 

result: 0=event posted, l=not posted 


Function: This routine adds an element to the system event queue. The 

specified event number and event message are logged for the 
event. The current time, mouse position, state of command 
key, option key, shift key, alpha lock key, and mouse button 
are also logged. An event is only posted if enabled by the system 
event mask; if not enabled, a result code of 1 is returned. 

This routine will delete the first element of the event queue 
(the oldest element), if the queue is full, to make room for 
the new event: this guarantees that an enabled event will be 
posted. 


Calling sequence: MOVE.W //EventNumber ,A0 

MOVE. L //Message, DO 
PostEvent 


Routine: OSEventAvail 

Arguments: AO (input) 

DO (input) 
DO (output) 


pointer to user event record (32-bit) 
set of events desired (event mask) 
0®non-null event returned, -l=null event 
returned 


Function: 


This routine polls for availability of certain types of events. 


If no events are available, the null event is returned along with 
a -1 result code in DO. Note that an event which is reported as 
available may disappear (i.e., not be accessible by a later 
call to GetOSEvent or OSEventAvail) in a busy environment due 
to the event buffer wraparound performed by PostEvent. 

Calling sequence: MOVE.W #EventMask,DO 

LEA EventBuf f er , AO 
OSEventAvail 


Routine : GetOSEvent 

Arguments: AO (input) — pointer to user event buffer (32-bit) 

DO (input) — type of event desired (event mask) 

DO (output) — O»non-null event returned, -l^null event 
returned 

Function: This routine returns the next event in the system event queue* 

The returned event is dequeued, thereby freeing up the space 
which holds that queue element (except for update events, which 
are never queued up) • If no events of the types enabled by the 
mask are enabled, the null event is returned* 

Calling sequence: MOVE.W #EventMask,DO 

LEA EventBuf fer ,A0 
GetOSEvent 




Routine: FlushEvents 

Arguments: DO (input) -- low word: events to remove (event mask) 

high word: events on which to stop (event mask) 
DO (output) -- event type of event which terminated search 

Function: This routine removes events of type specified by the caller* On 

entry, DO contains a long word of two 16-bit event masks* The 
low-order 16 bits contains a mask of events to remove, and the 
high-order 16 bits contains a mask of events that, once 
encountered, terminates the event removal process* DO returns 
0 if all events were deleted from the queue and, if not, the event 
number of the event which terminated the flush* 

Calling sequence: MOVE.L #EventMasks ,D0 

FlushEvents 


MACINTOSH USER EDUCATION 


The File Manager: A Programmer's Guide 


/OS/FS 


See Also: The Macintosh User Interface Guidelines 

The Memory Manager: A Programmer's Guide 

Inside Macintosh: A Road Map 

Macintosh Packages: A Programmer's Guide 

Programming Macintosh Applications in Assembly Language 




Modification History: First Draft (ROM 7) B. Hacker 3/02/84 


*** Review Draft. Not for distribution *** ABSTRACT 

This manual describes the File Manager, the part of the Macintosh 
Operating System that controls the exchange of information between a 
Macintosh application and files. 






2 


File Manager Programmer's Guide 


TABLE OF CONTENTS 


3 

3 

4 

5 
5 

9 

10 
11 

15 

16 
18 
22 

24 

25 
27 
29 

29 

30 

31 
31 
37 
47 
53 

55 

56 

56 

57 

58 

59 

60 
62 
64 

64 

65 
67 
74 


About This Manual 
About the File Manager 
Volumes 

Accessing Volumes 
Files 

Accessing Files 

File Information Used by the Finder 
Using the File Manager 
High-Level File Manager Routines 
Accessing Volumes 
Changing File Contents 
Changing Information About Files 
Low-Level File Manager Routines 
Routine Parameters 
I/O Parameters 
File Information Parameters 
Volume Information Parameters 
Routine Descriptions 

Initializing the File 1/0 Queue 
Accessing Volumes 
Changing File Contents 
Changing Information About Files 
Data Organization on Volumes 
Volume Information 
Volume Allocation Block Map 
File Directory 
File Tags on Volumes 
Data Structures in Memory 
The File I/O Queue 
Volume Control Blocks 
File Control Blocks 
File Tags in Memory 
The Drive Queue 
Using an External File System 
Summary of the File Manager 
Glossary 


Copyright (c) 1984 Apple Computer, Inc. All rights reserved. 

Distribution of this draft in limited quantities does not constitute 
publication. 


ABOUT THIS MANUAL 3 


ABOUT THIS MANUAL 


This manual describes the File Manager, the part of the Macintosh 
Operating System that controls the exchange of Information between a 
Macintosh application and files* *** Eventually It will become part of 
a larger manual describing the entire Toolbox and Operating System. 

*** The File Manager allows you to create and access any number of 
files containing whatever Information you choose. 

Like all Operating System documentation, this manual assumes you're 
familiar with Lisa Pascal. You should also be familiar with the 
following: 

- the basic concepts behind the Macintosh Operating System's Memory 
Manager 

- devices and device drivers, as described in the Inside Macintosh 
Road Map 

This manual is intended to serve the needs of both Pascal and 
assembly-language programmers. Information of interest to assembly- 
language progranmers only is isolated and labeled so that Pascal 
programmers can conveniently skip it. 

The manual begins with an introduction to the File Manager and what you 
can do with it. It then discusses some basic concepts behind the File 
Manager: what files and volumes are and how they're accessed. 

A section on using the File Manager introduces its routines and tells 
how they fit into the flow of your application. This is followed by 
sections explaining the File Manager's simplest, "high-level" Pascal 
routines and then its more complex, "low-level" Pascal and assembly- 
language routines. Both sections give detailed descriptions of all the 
procedures and functions, their parameters, calling protocol, effects, 
side effects, and so on. 

Following these descriptions are sections that won't interest all 
readers. The data structures that the File Manager uses to store 
information in memory and on disks are described, and special 
information is provided for programmers who want to write their own 
file system. 

Finally, there's a summary of the File Manager's data structures and 
routines, for quick reference, followed by a glossary of terms used in 
this manual. 


ABOUT THE FILE MANAGER 


The File Manager is the part of the Operating System that handles 
communication between applications and files on block devices such as 
disk drives. Files are a principal means by which data is stored and 
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transmitted on the Macintosh. A file is a named, ordered sequence of 
bytes. The File Manager contains routines used to read and write to 
files. 


Volumes 

A volume is a piece of storage medium, such as a disk, formatted to 
contain files. A volume can be an entire disk or only part of a disk. 
Currently, the 3 1 /2-inch Macintosh disks are one volume. 

(note) 

Specialized memory devices other than disks can also 
contain volumes, but the information in this manual 
applies only to volumes on disks. 

You identify a volume by its volume name , which consists of any 
sequence of 1 to 27 printing characters. Volume names must always be 
followed by a colon (:) to distinguish them from other names. 

(note) 

The colon (:) after a volume name should only be used 
when calling File Manager routines; it should never be 
seen by the user. 

A volume contains descriptive information about itself, including its 
name and a file directory listing information about files contained on 
the volume; it also contains files. The files are contained in 
allocation blocks , which are areas of volume space occupying multiples 
of 512 bytes. 

A volume can be mounted or unmounted. A volume becomes mounted when 
it’s in a disk drive and the File Manager reads descriptive information 
about the volume into memory. Once mounted, a volume may remain in a 
drive, or be ejected. Only mounted volumes are known to the File 
Manager, and an application can only access information on mounted 
volumes. A volume becomes unmounted when the File Manager releases the 
memory used to store the descriptive information. Your application 
would unmount a volume when it’s finished with the volume, or when it 
needs the memory occupied by the volume. 

The File Manager assigns each mounted volume a volume reference number 
you can use instead of its volume name to refer to it. Every mounted 
volume is also assigned a volume buffer on the heap, which is temporary 
storage space used when reading and writing information on the volume. 
The number of volumes that may be mounted at any time is limited only 
by the number of drives attached and available memory. 

A mounted volume can be on-line or off-line. A mounted volume is 
on-line as long as the volume buffer and all the descriptive 
information read from the volume when it was mounted remain in memory 
(about IK to 1.5K bytes); it becomes off-line when all but 94 bytes of 
descriptive information are released. You can access information on 
on-line volumes immediately, but off-line volumes must be placed 
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on-line before their information can be accessed. An application would 
place a volume off-line whenever it needed most of the memory the 
volume occupies. When you eject a volume from a drive , the File 
Manager automatically places the volume off-line. 

To prevent unauthorized writing to a volume, volumes can be locked . 
Locking a volume involves either setting a software flag on the volume, 
or changing some part of the volume physically v for example, sliding a 
tab from one position to another on a disk). Locking a volume ensures 
that none of the data on the volume can be changed. 


Accessing Volumes 

You can access a mounted volume via its volume name or volume reference 
number. On-line volumes in disk drives can also be accessed via the 
drive number of the drive on which the volume is mounted (the internal 
drive is number 1, and the external drive is number 2). You should 
always use the volume name or volume reference number, rather than a 
drive number, when accessing a mounted volume, because the volume may 
have been ejected or placed off-line. Whenever possible, use the 
volume reference number — to avoid confusion between volumes with the 
same name. 

One volume is always the default volume ♦ Whenever you call a routine 
to access a volume but don ? t specify which volume, the default volume 
is accessed. Initially, the volume used to start up the system is the 
default volume, but an application can designate any mounted volume as 
the default volume. 

Whenever the File Manager needs to access a mounted volume that f s been 
ejected from its drive, the dialog box shown in Figure 1 is displayed, 
and the File Manager waits until the user inserts the volume named 
volName into a drive. 



Please insert the disk: 
uolName 


Figure 1. Disk-Switch Dialog 
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Files 

A file is a finite sequence of numbered bytes* Any byte or group of 
bytes in the sequence can be accessed individually* A file is 
identified by its file name and version number * A file name consists 
of any sequence of 1 to 255 printing characters, excluding colons (:)• 
The version number is any number from 0 to 255, and is used by the File 
Manager to distinguish between different files with the same name. A 
byte within a file is identified by its position within the ordered 
sequence* 

(warning) 

Your application should constrain file names to fewer 
than 64 characters, because the Finder will generate an 
error if given a longer name. You should always assign 
files a version number of 0 , because the Resource Manager 
and Segment Loader won't operate on files with nonzero 
version numbers, and the Finder ignores version numbers* 

There are two parts or forks to a file: the data fork and the resource 
fork . Normally the resource fork of an application file contains the 
resources used by the application such as menus, fonts, end icons, and 
also the application code itself* The data fork can contain anything 
an application wants to store there. Information stored in resource 
forks should always be accessed via the Resource Manager* Information 
in data forks can only be accessed via the File Manager. For 
simplicity, we'll use "file" instead of "data fork" in this manual. 

A file can contain anywhere from 0 to 16,772,216 bytes (16 megabytes). 
Each byte is numbered: the first byte is byte 0. You can read bytes 
from and write bytes to a file either singly or in sequences of 
unlimited length. Each read or write operation can start anywhere in 
the file, regardless of where the last operation began or ended. 

Figure 2 shows the structure of a file. 


first 

byte 


current byte 



previous byl 


:e 


next byte 


last 

byte 


Figure 2. A File 

A file's maximum size is defined by its physical end-of-file , which is 
one greater than the number of the last byte in its last allocation 
block (Figure 3). The physical end-of-file is equivalent to the 
maximum number of bytes the file can contain. A file's actual size is 
defined by its logical end-of-file , which is one greater than the 
number of the last byte in the file. The logical end-of-file is 
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equivalent to the actual number of bytes in the file, since the first 
byte is byte number 0* The physical end-of-file is always greater than 
the logical end-of-file. For example, an empty file (one with 0 bytes) 
in a lK-byte allocation block has a logical end-of-file of 0 and a 
physical end-of-file of 1024. A file with 50 bytes has a logical 
end-of-file of 50 and a physical end-of-file of 1024. 


X X 


mark 

1 


byte 0 


logical physical 
end-of-file end-of-file 


mr 


byte 1024 


Figure 3. End-of-File and Mark 


The current position marker, or mark , is the number of the next byte 
that will be read or written. The value of the mark can't exceed the 
value of the logical end— of— file. The mark automatically moves forward 
one byte for every byte read from or written to the file. If, during a 
write operation, the mark meets the logical end-of-file, both are moved 
forward one position for every additional byte written to the file. 
Figure 4 shows the movement of the mark and logical end-of-file. 
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end -of -file 

¥ 

mark 

Beginning position 




end -of -file 



mark 

After reaffirm two bytes 


end-of-file 



After writing two bytes 






Figure 4. Movement of Logical End-of-File and Mark 

If, during a write operation, the mark must move past the physical ^ 

end-of-file, another allocation block is added to the file the 

physical end— of— file is placed one byte beyond the end of the new 

allocation block, and the mark and logical end-of-file are placed at 

the first byte of the new allocation block. 

An application can move the logical end— of— file to place it anywhere 
from the beginning of the file to the physical end-of-file (the mark is 
adjusted accordingly). If the logical end— of— file is moved to a 
position more than one allocation block short of the current physical 
end-of-file, the unneeded allocation block will be deleted from the 
file. The mark can be placed anywhere from the first byte in the file 
to the logical end-of-file. 
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Accessing Files 


A file can be open or dosed * An application can only perform certain 
operations, such as reading and writing, on open files; other 
operations, such as deleting, can only be performed on closed files. 

To open a file, you must identify it by name and version number and 
specify the volume containing the file. When a file is opened, the 
File Manager creates an access path , a description of the route to be 
followed when accessing the file. The access path specifies the volume 
on which the file is located (by volume reference number, drive number, 
or volume name) and the location of the file on the volume. Every 

access path is assigned a unique path reference number used to refer to 

it. You should always refer to a file via its path reference number, 
so that files with the same name aren't confused with one another. 

A file can have one access path open for writing or for both reading 
and writing, and one or more access paths for reading only; there 

cannot be more than one access path that writes to a file. Each access 

path is separate from all other access paths to the file. A maximum of 
12 access paths can be open at one time. Each access path can move its 
own mark, and read at the position it indicates. All access paths to 
the same file share common logical and physical end-of-file markers. 

The File Manager reads descriptive information about a newly opened 
file from its volume and stores it in memory. For example, each file 
has open permission information, which indicates whether data can only 
be read from it, or both read from and written to it. Each access path 
contains read /write permission information that specifies whether data 
is allowed to be read from the file, written to the file, both read and 
written, or whatever the file's open permission allows. If an 
application wants to write data to a file, both types of permission 

information must allow writing; if either type allows reading only, 

then no data can be written. 

When an application requests that data be read from a file, the File 
Manager reads the data from the file and transfers it to the 

application's data buffer . Any part of the data that can be 

transferred in entire 512-byte blocks is transferred directly. Any 
part of the data composed of fewer than 512 bytes is also read from the 
file in one 512-byte block, but placed in temporary storage space in 
memory. Then, only the bytes containing the requested data are 
transferred to the application. 

When an application writes data to a file, the File Manager transfers 
the data from the application's data buffer and writes it to the file. 
Any part of the data that can be transferred in entire 512-byte blocks 
is written directly. Any part of the data composed of fewer than 512 
bytes is placed in temporary storage space in memory until 512 bytes 
have accumulated; then the entire block is written all at once. 
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Normally the temporary space in memory used for all reading and writing 
is the volume buffer, but an application can specify that an access 
path buffer be used instead for a particular access path (Figure 5)* 



Figure 5. Buffers For Transferring Data 


(warning) 

You must lock every access path buffer you use, so its 
location doesn't change while the file is open. 

Your application can lock a file to prevent unauthorized writing to it. 

Locking a file ensures that none of the data in it can be changed *** 

The Finder doesn't treat locked and unlocked files differently ***• 

(note) 

Advanced programmers: The File Manager can also read a 
continuous stream of characters or a line of characters. 

In the first case, you ask the File Manager to read a 
specific number of bytes: when that many have been read 
or when the mark has reached the logical end-of-file, the 
read operation terminates. In the second case, called 
newline mode , the read will terminate when either of the 
above conditions is fulfilled or when a specified 
character, the newline character , is read. The newline 
character is usually Return (ASCII code $0D) , but can be 
any character whose ASCII code is between $00 and $FF, 
inclusive. Information about newline mode is associated 
with each access path to a file, and can differ from one 
access path to another. 


FILE INFORMATION USED BY THE FINDER 

A file directory lists information about all the files on a volume. 

The information used by the Finder is contained in a data structure of 
type FInfo: 
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TYPE FInfo 


RECORD 

f dType : OSType ; 

fdCreator: OSType; 
fdFlags: INTEGER; 

fdLocation: Point; 
fdFldr: INTEGER 

END; 


{type of file} 
{file's creator} 
{flags} 

{file's location} 
{file's window} 


Normally an application need only set the file type and creator when a 
file is created (see The Structure of a Macintosh Application ), and the 
Finder will manipulate the other fields* Advanced programmers may be 
interested in changing the contents of the other fields as well. 


FdFlags indicates whether the file's icon is invisible, whether the 
file has a bundle, and other characteristics used internally by the 
Finder: 

Bit Meaning if set 

5 File has a bundle 

6 File's icon is Invisible 

Masks for these two bits are built into the File Manager as predefined 
constants : 


CONST fHasBundle = 32; {file has a bundle} 

f Invisible = 64; {file's icon is invisible} 


You need only set the fHasBundle bit for documents with bundles. (The 
bundle bit for an application must have been set when the application 
was first installed.) FdFldr indicates the window in which the file's 
icon will appear: 


FdFldr Window 

-3 Trash 

-2 Desktop 

0 Disk 

>0 A folder 


If fdFldr contains a positive number, the file's icon will appear in a 
folder; the numbers that identify folders are assigned by the Finder. 
Advanced programmers can get the folder number of an existing file, and 
place additional files in that same folder. FdLocation contains the 
location of the file's icon in its window, given in the local 
coordinate system of the window. 


USING THE FILE MANAGER 


This section discusses how the File Manager routines fit into the 
general flow of an application program and gives an idea of what 
routines you'll need to use. The routines themselves are described in 
detail in the next two sections. 
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You can call File Manager routines via three different methods: 
high-level Pascal calls, low-level Pascal calls, and assembly language. 
The high-level Pascal calls are designed for Pascal programmers 
interested in using the File Manager in a simple manner; they provide 
adequate file I/O and don’t require much special knowledge to use. The 
low-level Pascal and assembly-language calls are designed for advanced 
Pascal programmers and assembly-language programmers interested in 
using the File Manager to its fullest capacity; they require some 
special knowledge to be used most effectively. 

Information for all programmers follows here. The next two sections 
contain special information for high-level Pascal programmers and for 
low-level Pascal and assembly-language programmers. 

(note) 

The names used to refer to routines here are actually the 
assembly-language macro names for the low-level routines, 
but the Pascal routine names are very similar. 

The File Manager is automatically initialized each time the system is 
started up. Pascal programs must must include QuickDraw in their USES 
declaration, because the File Manager uses the QuickDraw data type 
Point. 

To open an access path to a file, call Open. The File Manager creates 
an access path and returns a path reference number that you’ll use 
every time you want to refer to it. Before you open a file, you may 
want to call the Standard File Package, which presents a standard 
interface through which the user can specify the file to be opened. If 
the user inserts an unmounted volume into a drive, the Standard File 
Package will automatically attempt to mount it. The Standard File 
Package will return the name of the file, the volume reference number 
of the volume containing the file, and additional information. 

After a file has been opened, you can transfer data from it to an 
application's data buffer with Read, and send data from an 
application’s data buffer to the file with Write. Read and Write allow 
you to specify a byte position within the data buffer, a number of 
bytes to transfer, and the location within the file. You can’t use 
Write on a file whose open permission only allows reading, or on a file 
on a locked volume. 

Once you’ve completed whatever reading and writing you want to do, call 
Close to close the file. Close writes the contents of the file’s 
access path buffer to the volume and deletes the access path. You can 
remove a closed file (both forks) from a volume by calling Delete. 

To protect against power loss or unexpected disk ejection, you should 
periodically call FlushVol (probably after each time you close a file), 
which writes the contents of the volume buffer and all access path 
buffers (if any) to the volume, and updates the descriptive information 
contained on the volume. 
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Whenever your application Is finished with a disk, or the user chooses 
Eject from a menu, call Eject. Eject calls FlushVol, places the volume 
offline, and then physically ejects the volume from its drive. 

To create a new, empty file, call Create. Create allows you to set 
some of the information about the file stored on the volume. 

The preceding paragraphs covered the simplest File Manager routines: 
Open, Read, Write, Close, FlushVol, Eject, and Create. The remainder 
of this section describes the less commonly used routines, some of 
which are available only to advanced programmers. Skip the remainder 
of this section if the preceding paragraphs have provided you with all 
the information you want to know about using the File Manager. 

Some applications may want to mount volumes themselves, bypassing the 
implicit mounting performed by the Standard File Package. In this 
case, the application must eject an unwanted disk from its drive (if 
necessary), and request that the user insert a different disk. The 
File Manager will automatically attempt to mount the volume on the disk 
that's inserted. If you call the Toolbox Event Manager function 
GetNextEvent, it will return the disk inserted event: the low-order 
word of the event message will contain the number of the drive, and the 
high-order word will contain the result code of the attempted mounting. 
If the result code indicates that an error occurred, you'll need to 
call the Disk Initialization Package to allow the user to initialize or 
eject the volume. Your application can then call GetVolInfo, which 
will return the name of the volume, the amount of unused space on the 
volume, and a volume reference number that you can use every time you 
refer to that volume. 

To minimize the amount of memory used mounted volumes, an application 
can unmount or place off-line any volumes that aren't currently being 
used. To unmount a volume, call UnmountVol, which flushes a volume (by 
calling FlushVol) and deallocates all of the memory used for it 
(releasing about 1 to 1.5K bytes). To place a volume off-line, call 
Offline, which flushes a volume (by calling FlushVol) and deallocates 
all of the memory used for it except for 94 bytes of descriptive 
information about the volume. Off-line volumes are placed on-line by 
the File Manager as needed, but your application must remount any 
unmounted volumes it wants to access. The File Manager itself may 
place volumes off-line during its normal operation. 

If you would like all File Manager calls to apply to one volume, you 
can specify that volume as the default. You can use SetVol to set the 
default volume to any mounted volume, and GetVol to learn the name and 
volume reference number of the default volume. 

Normally, volume initialization and naming is handled by the Standard 
File Package, which calls the Disk Initialization Package. If you want 
to explicitly initialize a volume or erase all files from a volume, you 
can call the Disk Initialization Package directly. When you want to 
change the name of a volume, call the File Manager function Rename. 
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Applications normally will use the Resource Manager to open resource 
forks and change the information contained within, but programmers 
writing unusual applications (such as a disk-copying utility) might 
want to use the File Manager to open resource forks. This is done by 
calling OpenRF. As with Open, the File Manager creates an access path 
and returns a path reference number that you'll use every time you want 
to refer to this resource fork. 

As an alternative to specifying byte positions within a file with Read 
and Write, you can specify the byte position of the mark by calling 
SetFPos. GetFPos returns the byte position of the mark. 

Whenever a disk has been reconstructed in an attempt to salvage lost 
files (because its directory or other file-access information has been 
destroyed), the logical end-of-file of each file will probably be equal 
to each physical end-of-file, regardless of where the actual logical 
end-of-file is. The first time an application attempts to read from a 
file on a reconstructed volume, it will blindly pass the correct 
logical end-of-file and read misinformation until it reaches the new, 
incorrect logical end-of-file. To prevent this from occurring, an 
application should always maintain an independent record of the logical 
end-of-file of each file it uses. To determine the File Manager's 
conception of the length of a file, or find out how many-bytes have yet 
to be read from it, call GetEOF, which returns the logical end-of-file. 
You can change the length of a file by calling SetEOF. 

Allocation blocks are automatically added to and deleted from a file as 
necessary. If this happens to a number of files alternately, each of 
the files will be contained in allocation blocks scattered throughout 
the volume, which increases the time required to access those files. 

To prevent such fragmentation of files, you can allocate a number of 
contiguous allocation blocks to an open file by calling Allocate. 

Instead of calling FlushVol, an unusual application might call 
FlushFile. FlushFile forces the contents of a file's volume buffer and 
access path buffer (if any) to be written to its volume. FlushFile 
doesn't update the descriptive information contained on the volume, so 
the volume information won't be correct until you call FlushVol. 

To get information about a file (such as its name and creation date) 
stored on a volume, call GetFilelnfo. You can change this information 
by calling SetFllelnfo. Changing the name or version number of a file 
is accomplished by calling Rename or SetFilType, respectively; they 
will have a similar effect, since both the file name and version number 
are needed to identify a file. You can lock or unlock a file by 
calling SetFilLock or RstFilLock, respectively. 

You can't use Write, Allocate, or SetEOF on a locked file, a file whose 
open permission only allows reading, or a file on a locked volume. You 
can't use Rename or SetFilType on a file on a locked volume. 
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HIGH-LEVEL FILE MANAGER ROUTINES 


This section describes all the high-level Pascal routines of the File 
Manager. Assembly-language programmers cannot call these routines. 

For information on calling the low-level Pascal and assembly-language 
routines, see the next section. 

When accessing a volume, you must identify it by its volume name, its 
volume reference number, or the drive number of its drive — or allow the 
default volume to be accessed. The parameter names used in identifying 
a volume are volName, vRefNum, and drvNum. VRefNum and drvNum are both 
integers. VolName is a pointer, of type OSStrPtr, to a volume name. 

The File Manager determines which volume to access by using one of the 
following: 

1. VolName. (If volName points to a zero— length name, an error is 
returned.) 

2. If volName is NIL or points to an improper volume name, then 
vRefNum or drvNum (only one is given per routine). 

3. If vRefNum or drvNum is zero, the default volume. (If there isn't 
a default volume, an error is returned.) 

(warning) 

Before you pass a parameter of type OSStrPtr to a File 
Manager routine, be sure that memory has been allocated 
for the variable. For example, the following statements 
will ensure that memory is allocated: 

VAR myStr : OSStr255; 

BEGIN 

result := GetVol(@myStr,myRefNum) ; 

• e • 

f**' END; 

When accessing a closed £ile on a volume, you must identify the volume 
by the method given above, and identify the file by its name in the 
fileName parameter* The high-level File Manager routines assume that 
the file’s version number is 0* FileName can contain either the file 
name alone or the file name prefixed by a volume name* 

(note) 

Although fileName can include both the volume name and 
the file name, applications shouldn’t encourage users to 
prefix a file name with a volume name. 

You cannot specify an access path buffer when calling high-level Pascal 
routines* All access paths open on a volume will share the volume 
buffer, causing a slight increase in the amount of time required to 
access files* 
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All File Manager routines return a result code of type OSErr as their ’ 

function result. Each routine description lists all of the applicable ( 

result codes , along with a short description of what the result code 
means. Lengthier explanations of all the result codes can be found in 
the summary at -the end of this manual. 


Accessing Volumes 


FUNCTION GetVInfo (drvNum: INTEGER; VAR volName: OSStrPtr; VAR vRefNum: 

INTEGER; VAR freeBytes: Longlnt) : OSErr; 

GetVInfo returns the name, reference number, and available space (in 
bytes), in volName, vRefNum, and freeBytes, for the volume in the 
specified drive. 

Result codes noErr No error 

nsvErr No default volume 

paramErr Bad drive number 

FUNCTION GetVol (volName: OSStrPtr; VAR vRefNum: INTEGER) : OSErr; 

GetVol returns the name of the default volume in volName and its volume 
reference number in vRefNum. 

Result codes noErr No error 

nsvErr No default volume 


FUNCTION SetVol (volName: OSStrPtr; vRefNum: INTEGER) : OSErr; 


SetVol sets the default volume to 
volName or vRefNum. 

Result codes noErr 

bdNamErr 

nsvErr 

paramErr 


the mounted volume specified by 


No error 
Bad volume name 
No such volume 
No default volume 




! 
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FUNCTION FlushVol (volName: OSStrPtr; vRefNum: INTEGER) : OSErr; 

On the volume specified by volName or vRefNum, FlushVol writes the 
contents of the associated volume buffer and descriptive information 
about the volume (if they've changed since the last time FlushVol was 
called). 


Result codes noErr 

bdNamErr 

extFSErr 

ioErr 

nsDrvErr 

nsvErr 

paramErr 


No error 
Bad volume name 
External file system 
Disk I/O error 
No such drive 
No such volume 
No default volume 


FUNCTION UnmountVol (volName: OSStrPtr; vRefNum: INTEGER) : OSErr; 

UnmountVol unmounts the volume specified by volName or vRefNum, by 
calling FlushVol to flush the volume buffer, closing all open files on 
the volume, and releasing the memory used for the volume. 

(warning) 


Don't unmount 

the startup 

volume. 

Result codes 

noErr 

No error 


bdNamErr 

Bad volume name 


extFSErr 

External file system 


fnfErr 

File not found 


ioErr 

Disk I/O error 


nsDrvErr 

No such drive 


nsvErr 

No such volume 


paramErr 

No default volume 


FUNCTION Eject (volName: OSStrPtr; vRefNum: INTEGER) : OSErr; 

Eject calls FlushVol to flush the volume specified by volName or 
vRefNum, places the volume offline, and then ejects the volume. 

Result codes noErr 

bdNamErr 
extFSErr 
ioErr 
nsDrvErr 
nsvErr 
paramErr 


No error 
Bad volume name 
External file system 
Disk I/O error 
No such drive 
No such volume 
No default volume 
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Changing File Contents 


FUNCTION Create (fileName: OSStr255; vRefNum: INTEGER; creator: OSType; 
fileType: OSType) : OSErr; 

Create creates a new file with the specified name, file type, and 
creator, on the specified volume. The new file is unlocked and empty. 
Its modification and creation dates are set to the time of the system 
clock. 


Result codes noErr 

No error 

bdNamErr 

Bad file name 

dupFNErr 

Duplicate file name 

dirFulErr 

Directory full 

extFSErr 

External file system 

ioErr 

Disk I/O error 

nsvErr 

No such volume 

vLckdErr 

Software volume lock 

wPrErr 

Hardware volume lock 

FUNCTION FSOpen (fileName: OSStr255; 

vRefNum: INTEGER; VAR 

INTEGER) : OSErr; 

FSOpen creates an access path to the 

file having the name : 


the specified volume. A path reference number is returned in refNum. 
The access path's read/write permission is set to whatever the file's 
open permission allows. 


Result codes 


noErr 

No error 

bdNamErr 

Bad file name 

extFSErr 

External file system 

fnfErr 

File not found 

ioErr 

Disk I/O error 

mFulErr 

Memory full 

nsvErr 

No such volume 

opWrErr 

File already open for writing 

tmfoErr 

Too many files open 
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FUNCTION FSRead (refNum: INTEGER; VAR count: Longlnt; buffPtr: Ptr) : 
OSErr ; 


FSRead attempts to read the number of bytes specified by the count 
parameter from -the open file whose access path is specified by refNum, 
and transfer them to the data buffer pointed to by buffPtr. The read 
operation begins at the mark, so you might want to precede this with a 
call to SetFPos. If you try to read past the logical end-of-file, 
FSRead moves the mark to the end-of-file and returns eofErr as its 
function result. After the read is completed, the number of bytes 
actually read is returned in the count parameter. 


Result codes noErr 
eofErr 
extFSErr 
fnOpnErr 
ioErr 
paramErr 
rfNumErr 


No error 
End-of-file 
External file system 
File not open 
Disk I/O error 
Negative count 
Bad reference number 


FUNCTION FSWrite (refNum: INTEGER; VAR count: Longlnt; buffPtr: Ptr) : 
OSErr; 

FSWrite takes the number of bytes specified by the count parameter from 
the buffer pointed to by buffPtr and attempts to write them to the open 
file whose access path is specified by refNum. The write operation 
begins at the mark, so you might want to precede this with a call to 
SetFPos. After the write is completed, the number of bytes actually 
written is returned in the count parameter. 


Result codes 


noErr 

No error 

dskFulErr 

Disk full 

f LckdErr 

File locked 

fnOpnErr 

File not open 

ioErr 

Disk I/O error 

paramErr 

Negative count 

rfNumErr 

Bad reference number 

vLckdErr 

Software volume lock 

wPrErr 

Hardware volume lock 

wrPermErr 

Read/write or open permission 
doesn't allow writing 
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FUNCTION GetFPos (refNum: INTEGER; VAR filePos: Longlnt) : OSErr; 


GetFPos returns, in filePos, the mark of the open file whose access 
path is specified by refNum. 


Result codes noErr 

extFSErr 

fnOpnErr 

ioErr 

rfNumErr 


No error 

External file system 
File not open 
Disk I/O error 
Bad reference number 




FUNCTION SetFPos (refNum: INTEGER; posMode: INTEGER; posOff: Longlnt) : 
OSErr; 

SetFPos sets the mark of the open file whose access path is specified 
by refNum, to the position specified by posMode and posOff. PosMode 
indicates whether the mark should be set relative to the beginning of 
the file, the logical end-of-file, or the mark: 


PosMode 

0 

1 

2 

3 


Position 

Current position of mark (posOff is ignored) 
Relative to beginning of file 
Relative to logical end-of-file 
Relative to mark 


PosOff specifies the byte offset (either positive or negative) relative 
to posMode where the mark should actually be set. If you try to set 
the mark past the logical end-of-file, SetFPos moves the mark to the 
end-of-file and returns eofErr as its function result. 




Result codes noErr 

No error 


eofErr 

End-of-file 


extFSErr 

External file system 


fnOpnErr 

File not open 


ioErr 

Disk I/O error 


posErr 

Tried to position before start 



of file 


rfNumErr 

Bad reference number 


FUNCTION GetEOF (refNum: INTEGER; 

VAR logEOF: Longlnt) : OSErr; 



GetEOF returns, in logEOF, the logical end-of-file of the open file 
whose access path is specified by refNum. 


Result codes noErr 

extFSErr 

fnOpnErr 

ioErr 

rfNumErr 


No error 

External file system 
File not open 
Disk I/O error 
Bad reference number 
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FUNCTION SetEOF (refNum: INTEGER; logEOF: Longlnt) : OSErr; 

SeCEOF secs the logical end-of-file of the open file whose access path 
is specified by refNum, to the position specified by logEOF. If you 
attempt to set. the logical end-of-file beyond the physical end-of-file, 
the physical end-of-file is set to one byte beyond the end of the next 
free allocation block; if there isn't enough space on the volume, no 
change is made, and SetEOF returns dskFulErr as its function result. 

If logEOF is 0, all space on the volume occupied by the file is 
released. 


Result codes 


noErr 

No error 

dskFulErr 

Disk full 

extFSErr 

External file system 

fLckdErr 

File locked 

fnOpnErr 

File not open 

ioErr 

Disk I/O error 

rfNumErr 

Bad reference number 

vLckdErr 

Software volume lock 

wPrErr 

Hardware volume lock 

wrPermErr 

Read/write or open permission 
doesn't allow writing 




FUNCTION Allocate (refNum: INTEGER; VAR count: Longlnt) : OSErr; 

Allocate adds the number of bytes specified by the count parameter to 
the open file whose access path is specified by refNum, and sets the 
physical end-of-file to one byte beyond the last block allocated. The 
number of bytes allocated is always rounded up to the nearest multiple 
of the allocation block size, and returned in the count parameter. If 
there isn't enough empty space on the volume to satisfy the allocation 
request, the rest of the space on the volume is allocated, and Allocate 
returns dskFulErr as its function result. 


Result codes 


noErr 

No error 

dskFulErr 

Disk full 

fLckdErr 

File locked 

fnOpnErr 

File not open 

ioErr 

Disk I/O error 

rfNumErr 

Bad reference number 

vLckdErr 

Software volume lock 

wPrErr 

Hardware volume lock 

wrPermErr 

Read/write or open permission 
doesn’t allow writing 
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FUNCTION FSClose (refNum: INTEGER) : OSErr; 

FSClose removes the access path specified by refNum, writes the 
contents of the volume buffer to the volume, and updates the file's 
entry in the file directory. 

(note) 

Some information stored on the volume won't be correct 
until FlushVol is called. 

Result codes noErr 

extFSErr 
fnfErr 
fnOpnErr 
ioErr 
nsvErr 
rfNumErr 


Changing Information About Files 

All of the routines described in this section affect both forks of the 
file. 


No error 

External file system 
File not found 
File not open 
Disk I/O error 
No such volume 
Bad reference number 


FUNCTION GetFInfo (fileName: OSStr255; vRefNum: INTEGER; VAR fndrlnfo: 
FInfo) : OSErr; 

GetFInfo returns information about the file having the name fileName on 
the specified volume. Information used by the Finder is returned in 
fndrlnfo (see the "File Information Used by the Finder" section). 


Result codes noErr 

bdNamErr 

extFSErr 

fnfErr 

ioErr 

nsvErr 

paramErr 


No error 
Bad file name 
External file system 
File not found 
Disk I/O error 
No such volume 

Bad parameters and no default 
volume 




FUNCTION SetFInfo (fileName: OSStr255; vRefNum: INTEGER; fndrlnfo: 
FInfo) : OSErr; 


For the file having the name fileName on the specified volume, SetFInfo 
sets Information needed by the Finder to fndrlnfo (see the "File 
Information Used by the Finder" section). 


Result codes noErr 

extFSErr 

fLckdErr 

fnfErr 

ioErr 


No error 

External file system 
File locked 
File not found 
Disk I/O error 
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nsvErr 

vLckdErr 

wPrErr 


No such volume 
Software volume lock 
Hardware volume lock 


FUNCTION SetFLock (fileName: OSStr255; vRefNum: INTEGER) : OSErr; 

SetFLock locks the file having the name fileName on the specified 
volume. Access paths currently in use aren't affected. 


Result codes noErr 

extFSErr 

fnfErr 

ioErr 

nsvErr 

vLckdErr 

wPrErr 


No error 

External file system 
File not found 
Disk I/O error 
No such volume 
Software volume lock 
Hardware volume lock 


FUNCTION RstFilLock (fileName: OSStr255; vRefNum: INTEGER) : OSErr; 


RstFilLock unlocks the file having the name fileName on the specified 
volume. Access paths currently in use aren't affected. - 


Result codes noErr 

extFSErr 

fnfErr 

ioErr 

nsvErr 

vLckdErr 

wPrErr 


No error 

External file system 
File not found 
Disk I/O error 
No such volume 
Software volume lock 
Hardware volume lock 


FUNCTION Rename (oldName: OSStr255; vRefNum: INTEGER; newName: 

OSStr255) : OSErr; 

Given a file name in oldName, Rename changes the name of the file to 
newName. Access paths currently in use aren't affected. Given a 
volume name in oldName and a volume reference number in vRefNum, Rename 
changes the name of the specified volume to newName. 


Result codes 

noErr 

No error 



bdNamErr 

Bad file name 



dirFulErr 

Directory full 



dupFNErr 

Duplicate file name 



extFSErr 

External file system 



fLckdErr 

File locked 



fnfErr 

File not found 



fsRnErr 

Renaming difficulty 



ioErr 

Disk I/O error 



nsvErr 

No such volume 



paramErr 

Bad parameters and no 

default 



volume 



vLckdErr 

Software volume lock 
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wPrErr Hardware volume lock 




FUNCTION FSDelete (fileName: OSStr255; vRefNum: INTEGER) s OSErr; 

FSDelete removes the closed file having the name fileName from the 
specified volume* 

(note) 

This function will delete both forks of the file* 


Result codes 


noErr 

No error 


bdNamErr 

Bad file name 


extFSErr 

External file system 

f BsyErr 

File busy 


fLckdErr 

File locked 


fnfErr 

File not found 


ioErr 

Disk I/O error 


nsvErr 

No such volume 


vLckdErr 

Software volume 

lock 

wPrErr 

Hardware volume 

lock 




LOW-LEVEL FILE MANAGER ROUTINES 

This section contains special information for programmers using the 
low-level Pascal or assembly-language routines of the File Manager, and 
describes them in detail. 

You can execute most File Manager routines either synchronously 
(meaning that the application must wait until the routine is completed) 
or asynchronously (meaning that the application is free to perform 
other tasks while the routine is executing). MountVol, UnmountVol, 
Eject, and Off Line cannot be executed asynchronously, because they use 
the Memory Manager to allocate and deallocate memory. 

When an application calls a File Manager routine asynchronously, an 1/ 0 
request is placed in the file I/O queue , and control returns to the 
calling application — even before the actual I/O is completed. Requests 
are taken from the queue one at a time (in the same order that they 
were entered), and processed. Only one request may be processed at any 
given time. 

The calling application may specify a completion routine to be executed 
as soon as the I/O operation has been completed. 

At any time, you can use the InitQueue procedure to clear all queued 
File Manager calls except the current one. InitQueue is especially 
useful when an error occurs and you no longer wish queued calls to be 
executed. 




3/02/84 Hacker 


CONFIDENTIAL 


/0S/FS.A.1 


LOW-LEVEL FILE MANAGER ROUTINES 


25 


/‘"N 


Routine parameters passed by an application to the File Manager and 
returned by the File Manager to an application are contained in a 
parameter block , which is memory space in the heap or stack. Most 
low-level Pascal calls to the File Manager are of the form 

PBCallName (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 

PBCallName is the name of the routine. ParamBlock points to the 
parameter block containing the parameters for the routine. If async is 
TRUE, the call will be executed asynchronously; if FALSE, it will be 
executed synchronously* Each call returns an integer result code of 
type OSErr if an error occurred during the call. Each routine 
description lists all of the applicable result codes, along with a 
short description of what the result code means. Lengthier 
explanations of all the result codes can be found in the summary at the 
end of this manual. 






Assembly-language note : When you call a File Manager routine 
(except InitQueue), A0 must point to a parameter block 
containing the parameters for the routine. If you want the 
routine to be executed asynchronously, set bit 10. of the routine 
trap word. You can do this by supplying the word ASYNC as the 
second argument to the routine macro: for example 

_Read paramBlock, ASYNC 

If you want the routine to be executed synchronously, set bit 9 
of the routine trap word. This can be accomplished by supplying 
the word IMMED as the second argument to the routine macro: for 
example 

_Write paramBlock, IMMED 

All routines except InitQueue return a result code in D0. 


Routine Parameters 


There are three different kinds of parameter blocks you'll pass to File 
Manager routines. Each kind is used with a particular set of routine 
calls: I/O routines, file information routines, and volume information 
routines. 

The lengthy, variable-length data structure of a parameter block is 
given below. The Device Manager and File Manager use this same data 
structure, but only the parts relevant to the File Manager are shown 
here. Each kind of parameter block contains eight fields of standard 
information and nine to 16 fields of additional information: 
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TYPE ParamBlkType - (ioParam, fileParam, volumeParam, cntrlParam); 


ParamBlockRec 


« RECORD 


loLlnk: 

Ptr; 

ioType : 

INTEGER; 

ioTrap : 

INTEGER; 

ioCmdAddr : 

Ptr; 

ioCompletion: 

ProcPtr; 

ioResult: 

OSErr; 

IoNamePtr : 

OSStrPtr 

ioVRefNum: 

INTEGER; 


{next queue entry} 
{always 5} 

{routine trap} 
{routine address} 
{completion routine} 
{result code} 

{volume or file name} 
{volume reference or 
drive number} 


CASE ParamBlkType OF 
ioParam: 

... {I/O routine parameters} 
fileParam: 

. . . {file information routine parameters} 
volumeParam: 

. . . {volume information routine parameters} 


cntrlParam: 

. . . {Control and Status call parameters} 


END; 


ParmBlkPtr = ^ParamBlockRec; 


The first four fields in each parameter block are handled entirely by 
the File Manager, and most programmers needn't be concerned with them; 
programmers who are interested in them should see the section "Data 
Structures in Memory". 

IOCompletion contains the address of a completion routine to be 
executed at the end of an asynchronous call; it should be NIL for 
asynchronous calls with no completion routine, and is automatically set 
to NIL for all synchronous calls. For asynchronous calls, ioResult is 
positive while the routine is executing, and returns the result code. 
Your application can poll ioResult during the asynchronous execution of 
a routine to determine when the routine has completed. Completion 
routines are executed after ioResult is returned. 


LONamePtr points to either a volume name or a file name (which can be 
prefixed by a volume name). 

(note) 

Although ioNamePtr can include both the volume name and 
the file name, applications shouldn't encourage users to 
prefix a file name with a volume name. 

IOVRefNum contains either the reference number of a volume or the drive 
number of a drive containing a volume. 

For routines that access volumes, the File Manager determines which 
volume to access by using one of the following: 
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1. IONamePtr, a pointer to the volume name* 

2* If loNamePtr is NIL, or points to an improper volume name, then 
ioVRefNum. (If ioVRefNum is negative, it's a volume reference 
number; if positive, it's a drive number.) 

3. If ioVRefNum is 0, the default volume. (If there isn't a default 
volume, an error is returned.) 

For routines that access closed files, the File Manager determines 
which file to access by using ioNamePtr, a pointer to the name of the 
file (and possibly also of the volume). 

~ If the string pointed to by ioNamePtr doesn't include the volume 
name, the File Manager uses steps 2 and 3 above to determine the 
volume . 

— If ioNamePtr is NIL or points to an improper file name, an error 
is returned. 

The first eight fields are adequate for a few calls, but most of the 
File Manager routines require more fields, as described below. The 
parameters used with Control and Status calls< are described in the 
Device Manager manual *** doesn't yet exist ***. 


I/O Parameters 


When you call one of the I/O routines, use these nine additional fields 
after the standard 8-field parameter block: 


ioParam: 
ioRef Num: 
ioVersNum: 
ioPermssn: 
ioMisc : 
ioBuffer : 
loReqCount: 
ioActCount : 
ioPosMode: 

ioPosOffset: 


INTEGER; 
SlgnedBy te ; 
SignedBy te ; 
Ptr; 

Ptr; 

Longlnt; 

Longlnt; 

INTEGER; 

Longlnt; 


{path reference number} 
{version number} 

{read/write permission} 
{mlscellanous} 

{data buffer} 

{requested number of bytes} 
{actual number of bytes} 
{newline character and type of 
positioning operation} 

{size of positioning offset} 


For routines that access open files, the File Manager determines which 
file to access by using the path reference number in ioRefNum. 
IOPermssn requests permission to read or write via an access path: 


IOPermssn 

0 

1 

2 

3 


I/O operation 

Whatever is currently allowed 
Reading only 
Writing only 
Reading and writing 
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This request is compared with the open permission of the file* If the 
open permission doesn't allow I/O as requested, an error will be 
returned* 

The content of-ioMisc depends on the routine called; it contains either 
a pointer to an access path buffer, a new logical end-of-file, a new 
version number, or a pointer to a new volume or file name* Since 
ioMisc is of type Ptr, while end-of-file is Longlnt and version number 
is SignedByte, you'll need to use conversions like these: 

VAR pBlock: ParmBlkPtr; 
my Vers: SignedByte; 
myEOF : Longlnt ; 

pBlock~. ioMisc :=■ POINTER( 0RD4 (my Vers ) ) ; 
myVers := ORD(pBlock~. ioMisc) ; 

pBlock~ . ioMisc : = POINTER( 0RD4 (myEOF) ) ; 
myEOF := 0RD4(pBlock~. ioMisc) ; 

IOBuffer points to a data buffer into which data is written by Read 
calls and from which data is read by Write calls* IOReqCount specifies 
the requested number of bytes to be read, written, or allocated* 
IOActCount contains the number of bytes actually read, written, or 
allocated. 

IOPosMode and ioPosOffset contain positioning information used for 
Read, Write, and SetFPos calls. Bits 0 and 1 of ioPosMode indicate how 
to position the mark: 


IOPosMode 

0 

1 

2 

3 


Offset 

Current position of mark (ioPosOffset ignored) 
Relative to beginning of file 
Relative to logical end-of-file 
Relative to current mark 


IOPosOffset specifies the byte offset (either positive or negative) 
relative to ioPosMode where the operation will be performed. 


Assembly— language note : If bit 6 of ioPosMode is set, the File 
Manager will verify that all data read into memory by a Read 
call exactly matches the data on the volume (an error will be 
returned if any data don't match). 


(note) 

Advanced programmers: Bit 7 of ioPosMode is the newline 
flag — set if read operations should terminate at newline 
characters, and clear if reading should terminate at the 
end of the access path buffer or volume buffer. The 
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t 




hlgh-order byte of ioPosMode contains the ASCII code of 
the newline character* 




File Information Parameters 

When you call the GetFilelnfo and SetFilelnfo functions, use the 
following 16 additional fields after the standard 8-field parameter 
block: 


flleParam: 
(ioFRefNum: 
ioFVersNum: 
fillerl: 
ioFDir Index: 
ioFlAttrib: 
ioFIVersNum: 
ioFIFndrInfo 
loFINum: 
ioFIStBIk: 
ioFILgLen: 
ioFIPyLen: 
ioFIRStBIk 
ioFIRLgLen 
ioFIRPyLen 
ioFICrDat 
ioFlMdDat 


INTEGER; 

SignedBy te ; 

SignedByte ; 

INTEGER; 

SignedByte ; 

SignedByte ; 

FInfo; 

Longlnt; 

INTEGER; 

Longlnt; 

Longlnt; 

INTEGER; 

Longlnt; 

Longlnt; 

Longlnt; 

Longlnt) ; 


{path reference number} 

{version number} 

{not used} 

{file directory index} 

{file attributes} 

{version number} 

{information used by the Finder} 

{file number} 

{first allocation block of data fork} 
{logical end-of-file of data fork} 
{physical end-of-file of data fork} 

{first allocation block of resource fork} 
{logical end-of-file of resource fork} 
{physical end-of-file of resource fork} 
{date and time of creation} 

{date and time of last modification} 


IOFDir Index contains the file directory index, another method of 
referring to a file; most programmers needn't be concerned with 
information about file directories, but those interested can read the 
section "Data Organization on Volumes". 




Assembly-language note : IOFlAttrib contains eight bits of file 
attributes: if bit 7 is set, the file is open; if bit 0 is set, 
the file is locked. 


IOFlStBlk and ioFIRStBIk are zeroed if the file's data or resource fork 
is empty, respectively. The date and time in the ioFICrDat and 
ioFlMdDat fields are specified in seconds since 12:00 AM, January 1, 
1904. 


Volume Information Parameters 

When you call GetVolInfo, use the following 14 additional fields: 
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volumeParam: 


(flller2: 

Longlnt ; 

ioVol Index: 

INTEGER; 

loVCrDate : 

Longlnt ; 

ioVLsBkUp: 

Longlnt; 

ioVAtrb: 

INTEGER; 

ioVNmFls : 

INTEGER; 

ioVDirSt: 

INTEGER; 

ioVBILn: 

INTEGER; 

ioVNmAlBlks : 

INTEGER; 

ioVAlBlkSiz: 

Longlnt ; 

ioVClpSiz : 

Longlnt ; 

loAlBISt : 

INTEGER; 

ioVNxtFNum: 

Longlnt ; 

ioVFrBlk: 

INTEGER) 


> 


{not used} 

{volume index} 

{date and time of initialization} 

{date and time of last volume backup} 
{bit 15®1 if volume locked} 

{number of files in file directory} 
{first block of file directory} 

{number of blocks in file directory} 
{number of allocation blocks on volume} 
{number of bytes per allocation block} 
{number of bytes to allocate} 

{first block in volume block map} 

{next free file number} 

{number of free allocation blocks} 


lOVolIndex contains the volume index , another method of referring to a 
volume; the first volume mounted has an index of 1, and so on# Most 
programmers needn't be concerned with the parameters providing 
information about file directories and block maps (such as ioVNmFls), 
but interested programmers can read the section "Data Organization on 
Volumes" • 






Routine Descriptions 

This section describes the procedures and functions. Each routine 
description includes the low-level Pascal form of the call and the 
routine's assembly-language macro# A list of the fields in the 
parameter block affected by the call is also given# 


As sembly — language note : The field names given in these 
descriptions are those of the ParamBlockRec data type; see the 
"Summary of the File Manager" for the equivalent assembly- 
language equates# 


The number next to each parameter name indicates the byte offset of the 
parameter from the start of the parameter block pointed to by A0; only 
assembly— language programmers need be concerned with it# An arrow 
drawn next to each parameter name indicates whether it's an input , 
output, or input /output parameter: 

Arrow Meaning 

4 — Parameter must be passed to the routine 

— > Parameter will be returned by the routine 

Parameter must be passed to and will be returned 
by the routine 
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Initializing the File I/O Queue 


PROCEDURE InitQueue; 


Trap macro _Init Queue 

InitQueue clears all queued File Manager calls except the current one. 
There are no parameters or result codes associated with InitQueue* 


Accessing Volumes 




FUNCTION PBMountVol (paramBlock: ParmBlkPtr) : OSErr; 




Trap macro _MountVol 

Parameter block 

4 — 16 ioResult 

22 ioVRefNum 

Result codes noErr 

badMDBErr 

extFSErr 

ioErr 

mFulErr 

noMacDskErr 

nsDrvErr 

paramErr 

volOnLinErr 


word 

word 

No error 

Master directory block is bad 
External file system 
Disk I/O error 
Memory full 

Not a Macintosh volume 
No such drive 
Bad drive number 
Volume already on-line 


PBMountVol mounts the volume in the drive whose number is ioVRefNum, 
and returns a volume reference number in ioVRefNum. If there are no 
volumes already mounted, this volume becomes the default volume. 
PBMountVol is always executed synchronously. 
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FUNCTION PBGetVolInfo (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 


GetVolInfo 


Parameter block 


— » 

12 

ioCompletion 

pointer 


16 

ioResult 

word 

<-> 

18 

ioNamePtr 

pointer 


22 

ioVRefNum 

word 

— > 

28 

ioVolIndex 

word 

<— 

30 

ioVCrDate 

long word 

«— 

34 

ioVLsBkUp 

long word 


38 

ioVAtrb 

word 


40 

ioVNmFls 

word 


42 

ioVDirSt 

word 

«— 

44 

ioVBILn 

word 

<— 

46 

ioVNmAlBlks 

word 

<— 

48 

ioVAlBlkSiz 

long word 

<— 

52 

ioVClpSiz 

long word 


56 

ioAlBISt 

word 


58 

ioVNxtFNum 

long word 


62 

ioVFrBlk 

word 


Result codes 


noErr 

nsvErr 

paramErr 


No error 
No such volume 
No default volume 


PBGetVolInfo returns information about the specified volume* If 
ioVolIndex is positive, the File Manager attempts to use it to find the 
volume* If ioVolIndex is negative, the File Manager uses ioNamePtr and 
ioVRefNum in the standard way to determine which volume* If ioVolIndex 
is 0, the File Manager attempts to access the volume by using ioVRefNum 
only. The volume reference number is returned in ioVRefNum, and the 
volume name is returned in ioNamePtr, unless ioNamePtr is NIL. 
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FUNCTION PBGetVol (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro GetVol 


Parameter block 


— > 

12 

ioCompletion 

pointer 

4-- 

16 

ioResult 

word 

4 — 

18 

ioNamePtr 

pointer 

4 — 

22 

ioVRefNum 

word 

Result codes 

noErr No 

nsvErr No 

error 

default volume 


PBGetVol returns the name of the default volume in ioNamePtr and its 
volume reference number in ioVRefNum, unless ioNamePtr is NIL. 




FUNCTION PBSetVol (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 




Trap macro 

_SetVol 



Parameter block 




— > 

12 ioCompletion 

pointer 

4— 

16 ioResult 


word 

— » 

18 IoNamePtr 


pointer 

— > 

22 ioVRefNum 


word 

Result codes 

noErr 

No 

error 


bdNamErr 

Bad 

i volume name 


nsvErr 

No 

such volume 


paramErr 

No 

default volume 


PBSetVol sets the default volume to the mounted volume specified by 
IoNamePtr or ioVRefNum. 
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FUNCTION PBFlshVol (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 




Trap macro _FlushVol 

Parameter block 


— > 

12 

ioCompletion 

pointer 


16 

ioResult 

word 

— » 

18 

ioNamePtr 

pointer 

— » 

22 

IoVRefNum 

word 


Result codes noErr 

bdNamErr 
extFSErr 
ioErr 
nsDrvErr 
nsvErr 
paramErr 

PBFlshVol writes descriptive information, the contents of the 
associated volume buffer, and all access path buffers to the volume 
specified by ioNamePtr or ioVRefNum, to the volume (if they've changed 
since the last time PBFlshVol was called)* The volume modification 
date is set to the current time* 


No error 
Bad volume name 
External file system 
Disk I/O error 
No such drive 
No such volume 
No default volume 






3/02/84 Hacker 


CONFIDENTIAL 


/0S/FS.A.2 



LOW-LEVEL FILE MANAGER ROUTINES 


35 


FUNCTION PBUnmountVol (paramBlock: ParmBlkPtr) : OSErr; 


Trap macro UnmountVol 


Parameter block 



" 16 

ioResult 

word 

— » 

18 

ioNamePtr 

pointer 

—> 

22 

ioVRefNum 

word 

Result codes 

noErr 

bdNamErr 

extFSErr 

fnfErr 

ioErr 

nsDrvErr 

nsvErr 

paramErr 

No error 

Bad volume name 
External file system 
File not found 

Disk I/O error 

No such drive 

No such volume 

No default volume 


PBUnmountVol unmounts the volume specified by ioNamePtr or loVRefNum, 
by calling PBFlushVol to flush the volume, closing all open files on 
the volume, and releasing all the memory used for the volume* 
PBUnmountVol is always executed synchronously* 

(eye) 

Don't unmount the startup volume. 


FUNCTION PBOffLine (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _OffLine 

Parameter block 


— > 

12 

ioCompletion 

pointer 

«— 

16 

ioResult 

word 

—> 

18 

ioNamePtr 

pointer 

— > 

22 

ioVRefNum 

word 


Result codes noErr 

bdNamErr 

extFSErr 

ioErr 

nsDrvErr 

nsvErr 

paramErr 


No error 
Bad volume name 
External file system 
Disk I/O error 
No such drive 
No such volume 
No default volume 


PBOffLine places off-line the volume specified by ioNamePtr or 
ioVRefNum, by calling PBFlshVol to flush the volume, and releasing all 
the memory used for the volume except for 94 bytes of descriptive 
information. 
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FUNCTION PBEject (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro _Eject 

Parameter block 


— » 

12 

ioCompletion 

pointer 

<— 

16 

ioResult 

word 


18 

ioNamePtr 

pointer 

— > 

22 

ioVRefNum 

word 


Result codes noErr 

bdNamErr 

extFSErr 

ioErr 

nsDrvErr 

nsvErr 

paramErr 


No error 
Bad volume name 
External file system 
Disk I/O error 
No such drive 
No such volume 
No default volume 


PBEject calls PBOffLine to place the volume specified by ioNamePtr or 
ioVRefNum offline, and then ejects the volume. 


You may call PBEject asynchronously; the first part of the call is 
executed synchronously, and the actual ejection is executed 
asynchronously. 
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Changing File Contents 


FUNCTION PBCreate (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 


Create 


Parameter block 


— > 

12 

ioCompletion 

pointer 

«— 

16 

ioResult 

word 

— > 

18 

loNamePtr 

pointer 

— > 

22 

ioVRefNum 

word 


26 

IoVersNum 

byte 


Result codes noErr 

bdNamErr 

dupFNErr 

dirFulErr 

extFSErr 

ioErr 

nsvErr 

vLckdErr 

wPrErr 


No error 
Bad file name 
Duplicate file name 
Directory full 
External file system 
Disk I/O error 
No such volume 
Software volume lock 
Hardware volume lock 


PBCreate creates a new file having the name loNamePtr and the version 
number ioVersNum, on the specified volume* The new file is unlocked 
and empty* Its modification and creation dates are set to the time of 
the system clock* The application should call PBSetFInfo to fill in 
the information needed by the Finder. 
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FUNCTION PBOpen (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 

_Open 


Parameter block 

■— » 

12 ioCompletion pointer 

«— 

16 ioResult 

word 

— > 

18 IoNamePtr 

pointer 

—> 

22 ioVRefNum 

word 

<— 

24 IoRefNum 

word 


26 ioVer sNum 

byte 

— > 

27 ioPermssn 

byte 

—> 

28 ioMisc 

pointer 

Result codes 

noErr 

No error 


bdNamErr 

Bad file name 


extFSErr 

External file system 


fnfErr 

File not found 


ioErr 

Disk I/O error 


mFulErr 

Memory full 


nsvErr 

No such volume 


opWrErr 

File already open for writing 


tmfoErr 

Too many files open 


PBOpen creates an access path to the file having the name ioNamePtr and 
the version number ioVersNum, on the specified volume. A path 
reference number is returned in ioRefNum. 

XOMisc either points to a 522-byte portion of memory to be used as the 
access path's buffer, or is NIL if you want the volume buffer to be 
used instead. 

(eye) 

You should ensure that all access paths to a single file 
share the same buffer so that they will read and write 
the same data. 

IOPermssn specifies the path's read/write permission. A path can be 
opened for writing even if it accesses a file on a locked volume, and 
an error won't be returned until a PBWrite, PBSetEOF, or PBAllocate 
call is made. 

If you attempt to open a locked file for writing, PBOpen will return 
opWrErr as its function result. If you attempt to open a file for 
writing and it already has an access path that allows writing, PBOpen 
will return the reference number of the existing access path in 
IoRefNum and opWrErr as its function result. 
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FUNCTION PBOpenRF (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 




Trap macro 


ppenRF 


Parameter block 

12 

«— 16 
— > 18 

— > 22 

«— 24 

— > 26 

— > 27 

— > 28 


loCompletion 

pointer 

ioResult 

word 

loNamePtr 

pointer 

ioVRefNum 

word 

loRefNum 

word 

ioVersNum 

byte 

ioPermssn 

byte 

ioMlsc 

pointer 


Result codes noErr 

bdNamErr 

extFSErr 

fnfErr 

ioErr 

mFulErr 

nsvErr 

opWrErr 

permErr 

tmfoErr 

PBOpenRF is identical to PBOpen, 
resource fork instead of 


No error 
Bad file name 
External file system 
File not found 
Disk I/O error 
Memory full 
No such volume 

File already open for writing 
Open permission doesn't 
allow reading 
Too many files open 


except that it opens the file's 
its data fork* 
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FUNCTION PBRead (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 




Trap macro 


Read 


Parameter block 


—> 

12 

ioCompletion 

pointer 

<— 

16 

ioResult 

word 

— » 

24 

ioRefNum 

word 

— > 

32 

ioBuffer 

pointer 

— > 

36 

ioReqCount 

long word 

«— 

40 

IoActCount 

long word 

— > 

44 

ioPosMode 

word 


46 

ioPosOffset 

long word 


Result codes noErr 
eofErr 
extFSErr 
fnOpnErr 
ioErr 
paramErr 
rfNumErr 


No error 
End-of-file 
External file system 
File not open 
Disk I/O error 
Negative ioReqCount 
Bad reference number 


PBRead attempts to read ioReqCount bytes from the open file whose 
access path is specified by ioRefNum, and transfer them to the data 
buffer pointed to by ioBuffer. If you try to read past the logical 
end-of-file, PBRead moves the mark to the end-of-file and returns 
eofErr as its function result. After the read operation is completed, 
the mark is returned in ioPosOffset and the number of bytes actually 
read is returned in ioActCount. 


(note) 

Advanced programmers : IOPosMode contains the newline 
character (if any), and indicates whether the read should 
begin relative to the beginning of the file, the mark, or 
the end-of-file. The byte offset from the position 
indicated by ioPosMode, where the read should actually 
begin, is given by ioPosOffset. If a newline character 
is not specified, the data will be read one byte at a 
time until ioReqCount bytes have been read or the 
end-of-file is reached. If a newline character is 
specified, the data will be read one byte at a time until 
the newline character is encountered, the end-of-file is 
reached, or ioReqCount bytes have been read. 
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FUNCTION PBWrite (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 






Trap macro _Wrlte 


Parameter block 



12 

ioCompletlon 

pointer 

«— 

16 

ioResult 

word 

— > 

24 

IoRefNum 

word 

— > 

32 

ioBuffer 

pointer 

— > 

36 

ioReqCount 

long word 

4~ 

40 

ioActCount 

long word 

— > 

44 

ioPosMode 

word 

—> 

46 

ioPosOffset 

long word 


Result codes noErr 

dskFulErr 

f LckdErr 

fnOpnErr 

ioErr 

paramErr 

posErr 

rfNumErr 

vLckdErr 

wPrErr 

wrPermErr 


No error 

Disk full 

File locked 

File not open 

Disk I/O error 

Negative ioReqCount 

Position is beyond end-of-file 

Bad reference number 

Software volume lock 

Hardware volume lock 

Read/write or open permission 

doesn't allow writing 


PBWrite takes ioReqCount bytes from the buffer pointed to by ioBuffer 
and attempts to write them to the open file whose access path is 
specified by ioRefNum. After the write operation is completed, the 
mark is returned in ioPosOffset, and the number of bytes actually 
written is returned in ioActCount. 


IOPosMode indicates whether the write should begin relative to the 
beginning of the file, the mark, or the end-of-file. The byte offset 
from the position indicated by ioPosMode, where the read should 
actually begin, is given by ioPosOffset. 
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FUNCTION PBGetFPos (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 




GetFPos 


Parameter block 


— » 

12 

loCompletlon 

pointer 

<— 

16 

ioResult 

word 


22 

ioRefNum 

word 

«— 

36 

ioReqCount 

long word 


40 

IoActCount 

long word 


44 

IoPosMode 

word 

<— 

46 

ioPosOffset 

long word 


Result codes noErr 

extFSErr 

fnOpnErr 

ioErr 

rfNumErr 


No error 

External file system 
File not open 
Disk I/O error 
Bad reference number 


PBGetFPos returns, in ioPosOffset, the mark of the open file whose 
access path is specified by ioRefNum* GetFPos sets ioReqCount, 
ioActCount, and ioPosMode to 0. 



FUNCTION PBSetFPos (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 


SetFPos 


Parameter block 


— » 

12 

loCompletlon 

pointer 

«— 

16 

ioResult 

word 

— > 

22 

ioRefNum 

word 

—> 

44 

IoPosMode 

word 

— » 

46 

IoPosOffset 

long word 


Result codes noErr 
eofErr 
extFSErr 
fnOpnErr 
ioErr 
posErr 

rfNumErr 


No error 
End -of -file 
External file system 
File not open 
Disk I/O error 

Tried to position before start 
of file 

Bad reference number 



PBSetFPos sets the mark of the open file whose access path is specified 
by ioRefNum, to the position specified by ioPosMode and ioPosOffset. 
IoPosMode indicates whether the mark should be set relative to the 
beginning of the file, the mark, or the logical end-of-file. The byte 
offset from the position given by ioPosMode, where the mark should 
actually be set, is given by ioPosOffset. If you try to set the mark 
past the logical end-of-file, PBSetFPos moves the mark to the 
end-of-file and returns eofErr as its function result. 
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FUNCTION PBGetEOF (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 


GetEOF 


Parameter block 


— > 

12 

ioCompletion 

pointer 

<— 

16 

ioResult 

word 


22 

ioRefNum 

word 


28 

ioMisc 

long word 


Result codes noErr 

extFSErr 

fnOpnErr 

ioErr 

rfNumErr 


No error 

External file system 
File not open 
Disk I/O error 
Bad reference number 


PBGetEOF returns, in ioMisc, the logical end-of-file of the open file 
whose access path is specified by IoRefNum. 


FUNCTION PBSetEOF (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


ioCompletion 

ioResult 

ioRefNum 

ioMisc 


pointer 

word 

word 

long word 


Trap macro _SetEOF 

Parameter block 

— » 12 

<— 16 
— » 22 

—> 28 

Result codes noErr 

dskFulErr 

extFSErr 

fLckdErr 

fnOpnErr 

ioErr 

rfNumErr 

vLckdErr 

wPrErr 

wrPermErr 


No error 
Disk full 

External file system 

File locked 

File not open 

Disk I/O error 

Bad reference number 

Software volume lock 

Hardware volume lock 

Read/write or open permission 

doesn't allow writing 


PBSetEOF sets the logical end-of-file of the open file whose access 
path is specified by ioRefNum, to ioMisc. If the logical end-of-file 
is set beyond the physical end-of-file, the physical end-of-file is set 
to one byte beyond the end of the next free allocation block; if there 
isn't enough space on the volume, no change is made, and PBSetEOF 
returns dskFulErr as its function result. If ioMisc is 0, all space on 
the volume occupied by the file is released. 
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FUNCTION PBAllocate (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 




Trap macro 

_Allocate 


Parameter block 



— > 

12 loCompletion pointer 

<— 

16 ioResult 

word 

— » 

22 IoRefNum 

word 

— > 

36 ioReqCount 

long word 

<— 

40 ioActCount 

long word 

Result codes 

noErr 

No error 


dskFulErr 

Disk full 


fLckdErr 

File locked 


fnOpnErr 

File not open 


ioErr 

Disk I/O error 


rfNumErr 

Bad reference number 


vLckdErr 

Software volume lock 


wPrErr 

Hardware volume lock 


wrPermErr 

Read/write or open permission 


doesn’t allow writing 


PBAllocate adds ioReqCount bytes to the open file whose access path is 
specified by ioRefNum, and sets the physical end-of-file to one byte 
beyond the last block allocated* The number of bytes allocated is 
always rounded up to the nearest multiple of the allocation block size, 
and returned in ioActCount* If there isn’t enough empty space on the 
volume to satisfy the allocation request, PBAllocate allocates the rest 
of the space on the volume and returns dskFulErr as its function 
result* 
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FUNCTION PBFIshFile (paramBlock: ParmBIkPtr; async: BOOLEAN) : OSErr; 




Trap macro 


FlushFile 


Parameter block 

—> 12 
16 

— > 22 

Result codes noErr 

extFSErr 

fnfErr 

fnOpnErr 

ioErr 

nsvErr 

rfNumErr 


pointer 
word 
word 

No error 

External file system 
File not found 
File not open 
Disk I/O error 
No such volume 
Bad reference number 


ioCompletion 
ioResult 
ioRef Num 


PBFIshFile writes the contents of the access path buffer Indicated by 
ioRefNum to the volume, and updates the file's entry in the file 
directory. 


(eye) • . _ 

Some information stored on the volume won't be correct 
until PBFlshVol is called. 
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FUNCTION PBClose (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 

_Close 


Parameter block 

— » 

12 loCompletlon pointer 

<— 

16 ioResult 

word 

— > 

24 ioRefNum 

word 

Result codes 

noErr 

No error 


extFSErr 

External file system 


fnfErr 

File not found 


fnOpnErr 

File not open 


ioErr 

Disk I/O error 


nsvErr 

No such volume 


rfNumErr 

Bad reference number 


PBClose removes the access path specified by ioRefNum and writes the 
contents of the access path buffer to the volume* 

(eye) 

Some information stored on the volume won't be correct 
until PBFlshVol is called* 
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Changing Information About Files 

All of the routines described In this section affect both forks of a 
file. 


FUNCTION PBGetFInfo (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 

jGetFilelnfo 


Parameter block 




— > 

12 

ioCompletlon 

pointer 

4— 

16 

ioResult 

word 

— > 

18 

ioNamePtr 

pointer 

— » 

22 

ioVRefNum 

word 

4-- 

24 

ioRefNum 

word 

— » 

26 

ioVersNum 

byte 

— > 

28 

ioFDirlndex 

word 

4~ 

30 

ioFlAttrib 

byte 

4-- 

31 

ioFIVersNum 

byte 

4~ 

32 

ioFndrlnfo 

16 bytes 

4-- 

48 

loFINum 

long word 

4— 

52 

ioFIStBIk 

word 

4-- 

54 

ioFILgLen 

long word 

4— 

58 

ioFIPyLen 

long word 

4~ 

62 

ioFIRStBIk 

word 

4— 

64 

ioFIRLgLen 

long word 

4— 

68 

ioFIRPyLen 

long word 

4— 

72 

ioFICrDat 

long word 

4— 

76 

ioFlMdDat 

long word 

Result codes 

noEri 

No 

error 


bdNamErr Bad file name 


extFSErr External file system 


fnfErr File not found 


ioErr 

Disk I/O error 


nsvErr No 

such volume 


paramErr No 

default volume 


PBGetFInfo returns information about the specified file. If 
ioFDirlndex is positive, the File Manager returns information about the 
file whose file number is ioFDirlndex on the specified volume (see the 
section "Data Organization on Volumes" if you're interested in using 
this method). If ioFDirlndex is negative or zero, the File Manager 
returns information about the file having the name ioNamePtr and the 
version number ioVersNum, on the specified volume. Unless ioNamePtr is 
NIL, ioNamePtr returns a pointer to the name of the file. If the file 
is open, the reference number of the first access path found is 
returned in ioRefNum. 
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FUNCTION PBSetFInfo (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 


SecFllelnfo 


Parameter block 


“» 

12 

ioCompletlon 

pointer 

<— 

16 

ioResult 

word 

— > 

18 

ioNamePtr 

pointer 


22 

ioVRefNum 

word 


26 

ioVersNum 

byte 

— » 

32 

loFndrlnfo 

16 bytes 


72 

loFICrDat 

long word 

— > 

76 

ioFlMdDat 

long word 


Result codes noErr 

bdNamErr 

extFSErr 

fLckdErr 

fnfErr 

loErr 

nsvErr 

vLckdErr 

wPrErr 


No error 
Bad file name 
External file system 
File locked 
File not found 
Disk I/O error 
No such volume 
Software volume lock 
Hardware volume lock 


PBSetFInfo sets Information about the file (Including its creation and 
modification dates, and information needed by the Finder) having the 
name ioNamePtr and the version number ioVersNum on the specified 
volume. You should call PBGetFInfo just before PBSetFInfo, so the 
current information is present in the parameter block. 
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FUNCTION PBSetFLock (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 

_SetFilLock 



Parameter block 

—> 

12 ioCompletion pointer 


<— 

16 ioResult 

word 


— > 

18 ioNamePtr 

pointer 


— > 

22 ioVRefNum 

word 


—> 

26 ioVersNum 

byte 


Result codes 

noErr 

No error 



extFSErr 

fnfErr 

ioErr 

nsvErr 

External file system 
File not found 

Disk I/O error 

No such volume 


vLckdErr 

Software volume 

lock 


wPrErr 

Hardware volume 

lock 


PBSetFLock locks the file having the name ioNamePtr and the version 
number ioVersNum on the specified volume* Access paths currently in 
use aren't affected. 


FUNCTION PBRstFLock (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 

_RstFilLock 



Parameter block 

— > 

12 ioCompletion pointer 


«— 

16 ioResult 

word 



18 ioNamePtr 

pointer 


— > 

22 ioVRefNum 

word 


— > 

26 ioVersNum 

byte 


Result codes 

noErr 

No error 



extFSErr 

fnfErr 

ioErr 

nsvErr 

External file system 
File not found 

Disk I/O error 

No such volume 


vLckdErr 

Software volume 

lock 


wPrErr 

Hardware volume 

lock 


PBRstFLock unlocks tne file having the name ioNamePtr and the version 
number ioVersNum on the specified volume. Access paths currently in 
use aren't affected. 
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FUNCTION PBSetFVers (paramBlocks ParmBlkPtr; async: BOOLEAN) : OSErr; 




Trap macro 

_SetFilType 


Parameter block 


12 ioCompletion pointer 

<— 

16 ioResult 

word 


18 loNamePtr 

pointer 

— » 

22 ioVRefNum 

word 

— > 

26 loVersNum 

byte 

—> 

28 ioMisc 

byte 

Result codes 

noErr 

No error 


bdNamErr 

Bad file name 


dupFNErr 

Duplicate file name and version 


extFSErr 

External file system 


fLckdErr 

File locked 


fnfErr 

File not found 


nsvErr 

No such volume 


ioErr 

Disk I/O error 


paramErr 

No default volume 


vLckdErr 

Software volume lock 


wPrErr 

Hardware volume lock 


PBSetFVers changes the version number of the file having the name 
loNamePtr and version number loVersNum on the specified volume, to 
ioMisc. Access paths currently in use aren't affected. 

(warning) 

The Resource Manager and Segment Loader operate only on 
files with version number 0; changing the version number 
of a file to a nonzero number will prevent them from 
operating on it. 
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FUNCTION PBRename (paramBlock: ParmBlkPtr ; async: BOOLEAN) : OSErr; 




Trap macro _Rename 

Parameter block 

— 12 loCompletlon pointer 


«— 

16 

ioResult 

—> 

18 

ioNamePtr 

— > 

22 

ioVRefNum 

— > 

26 

ioVersNum 

—> 

28 

ioMisc 


Result codes noErr 

bdNamErr 

dirFulErr 

dupFNErr 

extFSErr 

fLckdErr 

fnfErr 

-'sRnErr 

ioErr 

nsvErr 

paramErr 

vLckdErr 

wPrErr 


word 

pointer 

word 

byte 

pointer 

No error 
Bad file name 
Directory full 

Duplicate file name and version 

External file system 

File locked 

File not found 

Renaming difficulty 

Disk I/O error 

No such, volume 

No default volume 

Software volume lock 

Hardware volume lock 


Given a file name in ioNamePtr and a version number in ioVersNum, 

Rename changes the name of the specified file to ioMisc; given a volume 
name in ioNamePtr or a volume reference number in ioVRefNum, it changes 
the name of the specified volume to ioMisc. Access paths currently in 
use aren't affected. 
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FUNCTION PBDelete (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 




Delete 


Parameter block 


— » 

12 ioCompletion pointer 



16 ioResult 

word 


— > 

18 ioNamePtr 

pointer 


— » 

22 ioVRefNum 

word 


— » 

26 ioVersNum 

byte 


Result codes 

noErr 

No error 



bdNamErr 

Bad file name 



extFSErr 

External file system 


fBsyErr 

File busy 



fLckdErr 

File locked 



fnfErr 

File not found 



nsvErr 

No such volume 



ioErr 

Disk I/O error 



vLckdErr 

Software volume 

lock 


wPrErr 

Hardware volume 

lock 


PBDelete removes the closed file having the name ioNamePtr and the 
version number ioVersNum, from the specified volume. You can't issue 
PBDelete to remove an open file. 


(note) 

This function will delete both forks of the file. 
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DATA ORGANIZATION ON VOLUMES 


This section explains how information is organized on volumes* Most of 
the information is accessible only through assembly language , but some 
advanced Pascal programmers may be interested* 

The File Manager communicates with device drivers that read and write 
data via block-level requests to devices containing Macintosh- 
initialized volumes* (Macintosh— initialized volumes are volumes 
initialized by the Disk Initialization Package*) The actual type of 
volume and device is unimportant to the File Manager; the only 
requirements are that the volume was initialized by the Disk 
Initialization Package and that the device driver be able to 
communicate via block-level requests* 

The 3 1/2-inch built-in and optional external drives are accessed via 
the Disk Driver* If you want to use the File Manager to access files 
on Macintosh-initialized volumes on other types of devices, you must 
write a device driver that can read and write data via block-level 
requests to the device on which the volume will be mounted* If you 
want to access files on nonMacintosh— initialized volumes, you must 
write your own external file system (see the section "Using an External 
File System"). 

The information on all block-initialized volumes is organized in 
logical blocks and allocation blocks* Logical blocks contain a number 
of bytes of standard information (512 bytes on Macintosh-initialized 
volumes), and an additional number of bytes of information specific to 
the disk driver (12 bytes on Macintosh-initialized volumes). 

Allocation blocks are composed of any integral number of logical 
blocks, and are simply a means of grouping logical blocks together in 
more convenient parcels* 

The remainder of this section applies only to Macintosh-initialized 
volumes* NonMacintosh— initialized volumes must be accessed via an 
external file system, and the information on them must be organized by 
an external initializing program* 

A Macintosh-initialized volume contains information needed to start up 
the system in logical blocks 0 and 1 (Figure 6). Logical block 2 of 
the volume begins the master directory block * The master directory 
block contains volume information and the volume allocation block map , 
which records whether each block on the volume is unused or what part 
of a file it contains data from* 
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logical block 0 

system startup 

logical block 1 

information 

logical block 2 

volume information 


logical block 3 

block mop 

unused 

logical block 4 



file directory 




logical block n 


logical block n+1 


unused 


7 file contents 7 


logical block 799 


[■ zero if not a startup disk 


l master directory block 


allocation block 2 


allocation block m 


Figure 6. A 400K-Byte Volume With lK-Byte Allocation Blocks 


The master directory "block" always occupies two blocks — the Disk 
Initialization Package varies the allocation block size as necessary to 
achieve this constraint. 

In the next logical block following the block map begins the file 
directory, which contains descriptions and locations of all the files 
on the volume. The rest of the logical blocks on the volume contain 
files or garbage (such as parts of deleted files). The precise format 
of the volume information, volume allocation block map, file directory, 
and files is explained in the following sections. 


Volume Information 


The volume information is contained in the first 64 bytes of the master 
directory block (Figure 7). This information is written on the volume 
when it's initialized, and modified thereafter by the File Manager. 
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byte 0 
2 
6 

10 

12 

14 

16 

18 

20 

24 

28 

30 

34 

36 

37 


always $D2D7 

date and time of intialization 
date and time of last backup 
volume attributes 
number of files in file directory 
first logical block of file directory 
number of logical blocks in file directory 
number of allocation blocks on volume 
size of allocation blocks 
number of bytes to allocate 
logical block number of first allocation block 
next unused file number ' 
number of unused allocation blocks 
length of volume name 
characters of volume name 

Figure 7. Volume Information 


drSigWord (word) 

drCrOate (long word) 

drLsBkUp (long word) 

drAtrb (word) 

drNmFIs (word) 

drOirSt (word) 

drBILen (word) 

drNnAIBIks (word) 

drAIBIkSiz (long word) 

drCIpSiz (long word) 

drAIBISt (word) 

drNxtFNum (long word) 

drFreeBks (word) 

drVN (byte) 

drVN + 1 (bytes) 


DrAtrb contains the volume attributes . Its bits, if set, indicate the 
following: 


Bit Meaning 

7 Volume is locked by hardware 

15 Volume is locked by software 

DrClpSiz contains the minimum number of bytes to allocate each time the 
Allocate function is called, to minimize fragmentation of files; it's 
always a multiple of the allocation block size. DrNxtFNum contains the 
next unused file number (see the "File Directory" section below for an 
explanation of file numbers). 
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Vr>i uma Allocation Block Map 

The volume allocation block map represents every allocation block on 
the volume with a 12-bit entry indicating whether the block is unused 
or allocated to a file. It begins in the master directory block at the 
byte following the volume information, and continues for as many 
logical blocks as needed. For example, a 400K-byte volume with a 
10-block file directory and lK-byte allocation blocks would have a 
591-byte block map. 

The first entry in the block map is for block number 2; the block map 
doesn't contain entries for the startup blocks. Each entry specifies 
whether the block is unused, whether it's the last block in the file, 
or which allocation block is next in the file: 

Entry Meaning 

0 Block is unused 

1 Block is the last block of the file 

2.. 4095 Number of next block in the file 

For instance, assume that there's one file on the volume, stored in 
allocation blocks 8, 11, 12, and 17; the first 16 entries of the block 
map would read 

000000 11 00 12 17 00001 

The first allocation block on a volume typically follows the file 
directory. The first allocation block is number 2 because of the 
special meaning of numbers 0 and 1. 

(note) 

As explained below, it's possible to begin the allocation 
blocks immediately following the master directory block 
and place the file directory somewhere within the 
allocation blocks. In this case, the allocation blocks 
occupied by the file directory must be marked with $FFF's 
in the allocation block map. 


File Directory 

The file directory contains an entry for each file. Each entry lists 
information about one file on the volume. Including its name and 
location. Each file is listed by its own unique file number , which the 
File Manager uses to distinguish it from other files on the volume. 

A file directory entry contains 51 bytes plus one byte for each 
character in the file name (Figure 8); if the file names average 20 
characters, a directory can hold seven file entries per logical block* 
Entries are always an integral number of words and don't cross logical 
block boundaries. The length of a file directory depends on the 
maximum number of files the volume can contain; for example, on a 
400K-byte volume the file directory occupies 12 logical blocks. 
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The £lle directory conventionally follows the block map and precedes 
the allocation blocks, but a volume-initializing program could actually 
place the file directory anywhere within the allocation blocks as long 
as the blocks occupied by the file directory are marked with $FFF's in 
the block map. 


byte 0 

fIFIegs (byte) 

1 

fITyp (byte) 

2 

flUsrWds (16 bytes) 

18 

fIFIIMum (long word) 

22 

fIStBIk (word) 

24 

fILgLen (long word) 

28 

flPyLen (long word) 

32 

flRStBlk (word) 

34 

fIRLgLen (long word) 

38 

fIRPyLen (long word) 

42 

fICrDet (long word) 

46 

flMdDat (long word) 

: 

50 

flNeme (byte) 

51 

fllslam + 1 (bytes) 

1 


bit 7=1 if entry meg bit 0=1 if file locked 
version number 

information used by the Finder 
file number 

first allocation block of data fork 
data fork's logical end-of-file 
data fork's physical end-of-file 
first allocation block of resource fork 
resource fork's logical end-of-file 
resource fork's physical end-of-file 
date and time file was created 
date and time file was last modified 
length of file name 
characters of file name 


Figure 8. A File Directory Entry 


FlStBlk and flRStBlk are 0 if the data or resource fork doesn't exist. 
FICrDat and flMdDat are given in seconds since 12:00 AM, January 1, 
1904. 


Each time a new file is created, an entry for the new file is placed in 
the file directory. Each time a file is deleted, its entry in the file 
directory is zeroed, and all blocks used by that file on the volume are 
released as free space. 


File Tags on Volumes 

As mentioned previously, logical blocks contain 512 bytes of standard 
information preceded by 12 bytes of file tags (Figure 9). The file 
tags are designed to allow easy reconstruction of files from a volume 
whose directory or other file-access information has been destroyed. 
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byte 0 

4 

5 

6 
8 


file number (long word) 
fork type (byte) 
file attributes (byte) 
file sequence (word) 
mod date (long word) 


file number 

bit 1 si if resource fork 
bit 7 = 1 if opens bit 0=1 if locked 
logical block sequence number 
date and time last modified 




Figure 9. File Tags on Volumes 

The file sequence indicates which relative portion of a file the block 
contains — the first logical block of a file has a sequence number of 0, 
the second a sequence number of 1 , and so on* 


DATA STRUCTURES IN MEMORY 


This section describes the memory data structures used by the File 
Manager and any external file system that accesses files on 
Macintosh-initialized volumes. Most of this information is accessible 
only through assembly language, but some advanced Pascal programmers 
may be interested* 

The data structures in memory used by the File Manager and all external 
file systems include: 

- the file I/O queue, listing the currently executing routine (if 
any), and any asynchronous routines awaiting execution 

- the volume —control “block queue, listing information about each 
mounted volume 

- copies of volume allocation block maps; one for each on-line 
volume 

- the file-control-block buffer, listing information about each 
access path 

- volume buffers; one for each on-line volume 

- optional access path buffers; one for each access path 

- the drive queue, listing information about each drive connected to 
the Macintosh 
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The File I/O Queue 


The file I/O queue contains a list of all asynchronous routines 
awaiting execution. Each time a routine is called, an entry is placed 
in the queue; each time a routine is completed, its entry is removed 
from the queue. Entries in the queue are processed in a first-in, 
first-out order. 

The file I/O queue is shown in Figure 10. Bit 7 of fsBusy is set if 
there are any entries in the queue. FSQHead points to first entry in 
the queue, and fsQTail points to the last entry in the queue. 



first queue last queue 

entry entry 


Figure 10. The File I/O Queue 


Each queue entry consists of a parameter block for the routine that was 
called. The structure of this block is shown in part below: 


TYPE ParamBlockRec = RECORD 

ioLlnk: 
ioType : 
ioTrap: 
ioCmdAddr : 

e e e 

END; 


Ptr; (next entry} 

INTEGER; {always fsQType} 
INTEGER; {routine trap} 
Ptr; {routine address} 
{rest of block} 


IOLink points to the next entry in the queue, and ioType indicates the 
queue type, which should always be the value of the predefined constant 
fsQType. IOTrap and ioCmdAddr contain the trap word and address of the 
File Manager routine that was called. 


You can refer to the file I/O queue by using the system global fsQHdr, 
which points to the fsBusy word. 
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Volume Control Blocks 

Each time a volume Is mounted. Its volume Information Is read from the 
volume and used to build a new volume control block in the 
volume -control-block queue (unless an ejected or off-line volume is 
being remounted)* A copy of the volume block map is also read from the 
volume and placed in the system heap, and a volume buffer. is created on 
the system heap* 

The volume-control-block queue is a list of the volume control blocks 
for all mounted volumes, maintained on the system heap. Its data 
structure is shown in Figure 11. Bit 7 of qFlags is set if there are 
any entries in the queue. QHead points to first entry in the queue, 
and qTail points to the last entry in the queue. 



lirat queue last queue 

entry entry 


Figure 11. Volume-Control-Block Queue 

Each queue entry consists of six bytes followed by a volume control 
block (Figure 12). A volume control block is a 94-byte nonrelocatable 
block that contains volume-specific information, including the first 64 
bytes of the master directory block (bytes 8 to 72 of the volume 
control block match bytes 0 to 64 of the volume information). 
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byteO 

qLink (pointer) 

pointer to next queue entry 

4 

qType (word) 

not used 

6 

vcbFIags (word) 

bit 15 si if volume control block is dirty 

8 

vcbSigWord (word) 

always $02D7 

1° 

vcbCrOate (long word) 

date and time volume was initialized 

14 

vcbLsBkllp (long word) 

date and time l8st backup copy was made 

18 

vcbAtrb (word) 

volume attributes 

20 

vcbNmFIs (word) 

number of files in file directory 

22 

vcbOirSt (word) 

first logical block of file directory 

24 

vcbBILn (word) 

length of file directory 

26 

vcbNmBIks (word) 

number of allocation blocks on volume 

28 

vcbAIBIkSiz (long word) 

size of allocation blocks 

32 

vcbCIpSiz (long word) 

number of bytes to allocate 

36 

vcbAIBISt (word) 

first logical block in block map 

38 

vcbNxtFNum (long word) 

next unused file number 

42 

vcbFreeBks (word) 

number of unused allocati on blocks 

44 

vcbVN (byte) 

1 length of volume name 

45 

vcbVN+l (bytes) 

characters of volume name 

72 

vcbDrvNum (word) 

drive number of drive in which 
volume is mounted 

74 

vcbDRefNum (word) 

driver reference number of driver for 
drive in which volume is mounted 

ID for file system handling volume 

76 

vcbFSID (word) 

78 

vcbVRefNum (word) 

volume reference number 

80 

vcbMAdr (pointer) 

memory location of volume block map 

84 

vcbBufAdr (pointer) 

memory location of volume buffer 

88 

vcbMLen (word) 

number of bytes in volume block map 

90 

vcbDir Index (word) 

for internal File Manager use 

92 

vcbDirBIk (word) 

for internal File Manager use 


Figure 12. A Volume Control Block 
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QLink points to the next entry in the queue. 

Bit 15 of vcbFlags is set if the volume information has been changed by 
a routine call since the volume was last affected by a FlushVol call. 
VCBAtr contains the volume attributes. Each bit, if set, indicates the 
following: 

Bit Meaning 

0-2 Inconsistencies were found between the volume information 

and the file directory when the volume was mounted 

6 Volume is busy (one or more files are open) 

7 Volume is locked by hardware 

15 Volume is locked by software 

VCBDrvNum contains the drive number of the drive on which the volume is 
mounted; vcbDRefNum contains the driver reference number of the driver 
used to access on volume is mounted. When a mounted volume is placed 
off-line, vcbDrvNum is zeroed. When ejected, vcbDrvNum is zeroed and 
vcbDRefNum is set to the negative of vcbDrvNum (becoming a positive 
number). VCBFSID identifies the file system handling the volume; it f s 
0 for volumes handled by the File Manager, and nonzero for volumes 
handled by other file systems. 

When a volume is placed off-line, its buffer and block map are 
deallocated. When a volume is unmounted, its volume control block is 
removed from the volume-control-block queue. 

You can refer to the volume-control-block queue by using the system 
global vcbQHdr , which points to the qFlags word. The default volume's 
volume control block is pointed to by the system global defVCBPtr. 


File Control Blocks 

Each time a file is opened, the file's directory entry is used to build 
a 30-byte file control block in the file-control-block buffer , which 
contains information about all access paths. The file-control-block 
buffer can contain up to 12 file control blocks (since up to 12 paths 
can be open at once), and is a 362-byte (2 + 30 bytes*12 paths) 
nonrelocatable block on the system heap (see Figure 13). 
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byte 0 
2 

32 


62 


z 


332 


length (word) 


first file 
control block 


second file 
control block 


twelfth file 
control block 


i 


Figure 13. The File-Control-Block Buffer 

You can refer to the file— control— block buffer by using the system 
global fcbSPtr, which points to the length word* Each file control 
block contains 30 bytes .of information about an access path (Figure 
14). 

file number 
flags 

version number 
first allocation block of file 
logical end-oMile 
physical end-of-file 
mark 

location of volune control block 
location of access path buffer 
for internal use of File Manager 


Figure 14. A File Control Block 

^ fcbMdRByt is set if the file has been changed since it was 
last flushed; bit 1 is set if the entry describes a resource fork; bit 
0 is set if data can be written to the file. 


byte 0 

4 

5 

6 
8 

12 

16 

20 

24 

28 


fcbFINum (long word) 


fcbMdRByt (byte) 


fcbTypByt (byte) 


fcbSBIk (word) 


fcbEOF (long word) 


fcbPLen (long word) 


fcbCrPs (long word) 


fcbVPtr (pointer) 


fcbBfAdr (pointer) 


fcbFIPos (word) 
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Files Tags in Memory 


As mentioned previously , logical blocks on Macintosh-initialized 
volumes contain 12 bytes of file tags. Normally, you'll never need to 
know about file tags, and the File Manager will let you read and write 
only the 512 bytes of standard information in each logical block. The 
File Manager automatically removes the file tags from each logical 
block it reads into memory (Figure 15) and places them at the location 
referred to by the system global tagData + 2. It replaces the last 
four bytes of the file tags with the number of the logical block from 
which the file was read (leaving a total of 10 bytes). 


byte 0 

4 

5 

6 
8 


file number (long word) 
fork type (byte) 
file attributes (byte) 
file sequence (word) 
logical block number (word) 


file number 

bit 1 si if resource fork 
bit 0 = 1 if locked 
logical block sequence number 
logical block 




Figure 15. File Tags in Memory 


(note) 

Access path buffers and volume buffers are 522 bytes long 
in order to contain the ten bytes of file tags and 512 
bytes of standard information. 


The Drive Queue 

Disk drives connected to the Macintosh are opened when the system 
starts up, and information describing each is placed in the drive 
queue . The data structure of the drive queue is shown in Figure 16. 
QHead points to the first entry in the queue, and qTail points to the 
last entry in the queue. 
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first queue last queue 

entry entry 

Figure 16* Drive Queue 


Each queue entry contains 12 bytes of information about each drive* 
QLink points to the next entry in the queue; qType is ignored* QDrvNum 
contains the drive number of the drive on which the volume is mounted; 
qDRefNum contains the driver reference number of the driver controlling 
the device on which the volume is mounted. QFSID identifies the file 
system handling the volume in the drive; it's 0 for volumes handled by 
the File Manager, and nonzero for volumes handled by other file 
systems. DQDrvSize contains the number of 512-byte blocks the volumes 
mounted in this drive contain* 

You can refer to the drive queue by using the system global drvQHdr, 
which points to the qFlags word* The drive queue can support any 
number of drives, limited only by memory space. 


USING AN EXTERNAL FILE SYSTEM 


The File Manager is used to access files on Macintosh-initialized 
volumes. If you want to access files on nonMacintosh-initialized 
volumes, you must write your own external file system and 
volume-initializing program. After the external file system has been 
written, it must be used in conjunction with the File Manager as 
described in this section. 

Before any File Manager routines are called, you must place the memory 
location of the external file system in the system global toExtFS, and 
link the drive(s) accessed by your file system into the drive queue. 

As each nonMacintosh-initialized volume is mounted, you must create 
your own volume control block for each mounted volume and link each one 
into the volume-control-block queue. As each access path is opened, 
you must create your own file control block and add it to the 
file-control-block buffer. 

All SetVol, GetVol, and GetVolInfo calls then can be handled by the 
File Manager via the volume-control-block queue and drive queue; 
external file systems needn't support these calls. 
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When an application calls any other File Manager routine accessing a 
nonMacintosh-initialized volume, the File Manager passes control to the 
address contained in toExtFS (if toExtFS is 0 , the File Manager returns 
directly to the application with an extFSErr). The external f £ le 
system must then use the information in the file I/O queue to handle 
the call as it wishes, clear the extFSErr condition, and return control 
to the File Manager. Control is passed to an external file system for 
the following specific routine calls: 

- For MountVol if the drive queue entry for the requested drive has 
a nnnxero file-svstem identifier. 


- For Create, Open, OpenRF, GetFilelnfo, SetFilelnfo, SetFilLock, 
RstFilLock, SetFilType, Rename, Delete, FlushVol, Eject, Off Line, 
and UnmountVol, if the volume control block for the requested file 
or volume has a nonzero file-system identifier. 


- For Close, Read, Write, Allocate, GetEOF, SetEOF, GetFPos, 
SetFPos, and FlushFile, if the file control block for the 
requested file points to a volume control block with a nonzero 
file-system identifier. 
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SUMMARY OF THE FILE MANAGER 


Constants 

CONST f Has Bundle - 32; 
f Invisible * 64; 




f^S 




Data Structures 

YPE FInfo = RECORD 

f dType : OSType ; 

fdCreator: OSType; 
f dFlags : INTEGER; 

fdLocation: Point; 
fdFldr: INTEGER 

END; 

ParmBlkPtr = “ParamBlockRec ; 

ParamBlkType = (ioParam, fileParam, volumeParam, cntrlParam); 

ParamBlockRec = RECORD 

ioLink: QElemPtr; 

ioType: INTEGER; 

ioTrap : INTEGER; 

ioCmdAddr: Ptr; 

ioCompletion: ProcPtr; 
ioResult: INTEGER; 

ioNamePtr: OSStrPtr; 

ioVRefNum: INTEGER; 


CASE ParamBlkType 

OF 

ioParam: 

(ioRefNum: 

INTEGER; 

ioVersNum: 

SignedBy te ; 

ioPermssn: 

SignedByte; 

ioMisc: 

Ptr; 

ioBuf fer: 

Ptr; 

ioReqCount: 

Longlnt; 

ioActCount : 

Longlnt; 

ioPosMode: 

INTEGER; 

ioPosOf f set 

Longlnt) ; 

fileParam: 

(ioFRefNum: 

INTEGER; 

ioCVersNum: 

SignedByte; 

fillerl : 

SignedByte; 

ioFDir Index: 

INTEGER; 

ioFlAttrib: 

SignedByte ; 

ioFIVersNum: 

SignedByte ; 

ioFIFndrInfo 

: FInfo; 

ioFINum: 

Longlnt; 
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ioFIStBIk: 

INTEGER; 

loFILgLen: 

Longlnt ; 

ioFIPyLen: 

Longlnt; 

ioFIRStBIk 

INTEGER; 

loFIRLgLen 

Longlnt; 

ioFIRPyLen 

Longlnt; 

ioFICrDat 

Longlnt ; 

ioFlMdDat 

Longlnt) 

volumeParam: 


(filler2: 

Longlnt ; 

ioVol Index: 

INTEGER; 

loVCrDate: 

Longlnt; 

ioVLsBkUp: 

Longlnt; 

ioVAtrb: 

INTEGER; 

ioVNmFls: 

INTEGER; 

ioVDirSt: 

INTEGER; 

ioVBILn: 

INTEGER; 

ioVNmAlBlks: 

INTEGER; 

ioVAlBlkSiz: 

Longlnt; 

ioVClpSiz: 

Longlnt; 

ioAlBISt : 

INTEGER; 

ioVNxtFNum: 

Longlnt; 

ioVFrBlk: 

INTEGER) ; 


cntrlParam: 

{used by Device Manager} 

END; 


High-Level Routines 


Accessing Volumes 


FUNCTION GetVInfo 


FUNCTION GetVol 

FUNCTION SetVol 
FUNCTION FlushVol 
FUNCTION UnmountVol 
FUNCTION Eject 


(drvNum: 
vRefNum: 
OSErr ; 
(volName: 
OSErr; 
(volName: 
(volName: 
(volName : 
(volName : 


INTEGER; VAR volName: OSStrPtr; VAR 
INTEGER; VAR freeBytes: Longlnt) : 

OSStrPtr; VAR vRefNum: INTEGER) : 


OSStrPtr; 

OSStrPtr; 

OSStrPtr; 

OSStrPtr; 


vRefNum: 

vRefNum: 

vRefNum: 

vRefNum: 


INTEGER) 

INTEGER) 

INTEGER) 

INTEGER) 


: OSErr; 
: OSErr; 
: OSErr; 
: OSErr; 


Changing File Contents 


FUNCTION Create 

FUNCTION FSOpen 
FUNCTION FSRead 


(fileName: OSStr255; versNum: SignedByte; vRefNum: 
INTEGER; creator: OSType; fileType: OSType) : 

OSErr ; 

(fileName: OSStr255; versNum: SignedByte; vRefNum: 

INTEGER; VAR refNum: INTEGER) : OSErr; 

(refNum: INTEGER; VAR count: Longlnt; buffPtr: Ptr) 
: OSErr; 
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FUNCTION FSWrite 

FUNCTION GetFPos 
FUNCTION SetFPos 

FUNCTION GetEOF 
FUNCTION SetEOF 
FUNCTION Allocate 
FUNCTION FSClose 


(refNum: INTEGER; VAR count: Longlnt; buffPtr: Ptr) 

: OSErr; 

(refNum: INTEGER; VAR filePos: Longlnt) : OSErr; 
(refNum: INTEGER; posMode: INTEGER; posOff: Longlnt) 
: OSErr; 

(refNum: INTEGER; VAR logEOF: Longlnt) : OSErr; 
(refNum: INTEGER; logEOF: Longlnt) : OSErr; 

(refNum: INTEGER; VAR count: Longlnt) :. OSErr; 
(refNum: INTEGER) : OSErr; 


Changing Information About Files 


FUNCTION 

FUNCTION 

FUNCTION 

FUNCTION 

FUNCTION 


GetFInfo 

SetFInfo 

SetFLock 

RstFLock 

Rename 


FUNCTION FSDelete 


(file Name: 
fndrlnfo: 
(fileName: 

FInfo) : 
(fileName: 
(fileName: 
( oldName : 
OSStr255) 
(fileName: 


OSStr255 
FInfo) : 

OSStr255 
OSErr; 

OSStr255 
OSStr255 
OSStr255; 

: OSErr ; 

OSStr255; vRefNum: INTEGER) : OSErr; 


i; vRefNum: 

OSErr; 
i; vRefNum: 

i ; vRefNum : 
>; vRefNum: 
vRefNum 


INTEGER; VAR 

INTEGER; fndrlnfo: 

: INTEGER) : OSErr; 

: INTEGER) : OSErr; 
INTEGER; newName: 


Low-Level Routines 


Initialization 


PROCEDURE Ini tQueue ; 


Accessing Volumes 


FUNCTION PBMountVol 
FUNCTION PBGetVolInfo 
FUNCTION PBGetVol 
FUNCTION PBSetVol 
FUNCTION PBFlushVol 
FUNCTION PBUnmountVol 
FUNCTION PBOffLlne 
FUNCTION PBEject 


( paramBlock : 
( paramBlock : 
(paramBlock: 
(paramBlock: 
( paramBlock : 
(paramBlock: 
(paramBlock: 
(paramBlock: 


ParmBlkPtr) 

ParmBlkPtr; 

ParmBlkPtr; 

ParmBlkPtr; 

ParmBlkPtr; 

ParmBlkPtr) 

ParmBlkPtr; 

ParmBlkPtr; 


: OSErr; 
async: BOOLEAN) 
as ync : BOOLEAN ) 
async: BOOLEAN) 
async: BOOLEAN) 
: OSErr; 
async: BOOLEAN) 
async: BOOLEAN) 


Changing File Contents 


FUNCTION PBCreate 
FUNCTION PBOpen 
FUNCTION PBOpenRF 
FUNCTION PBRead 
FUNCTION PBWrite 
FUNCTION PBGetFPos 
FUNCTION PBSetFPos 


(paramBlock: ParmBlkPtr; async: BOOLEAN) 
(paramBlock: ParmBlkPtr; async: BOOLEAN) 
(paramBlock: ParmBlkPtr; async: BOOLEAN) 
(paramBlock: ParmBlkPtr; async: BOOLEAN) 
(paramBlock: ParmBlkPtr; async: BOOLEAN) 
(paramBlock: ParmBlkPtr; async: BOOLEAN) 
(paramBlock: ParmBlkPtr; async: BOOLEAN) 


: OSErr; 
: OSErr ; 
: OSErr; 
: OSErr ; 

: OSErr; 
: OSErr; 


OSErr; 
OSErr; 
OSErr; 
OSErr; 
OSErr; 
OSErr; 
OSErr ; 
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FUNCTION PBGetEOF (paramBlock: 
FUNCTION PBSetEOF (paramBlock: 
FUNCTION PBA1 locate (paramBlock: 
FUNCTION PBFlushFile (paramBlock: 
FUNCTION PBClose (paramBlock: 


ParmBlkPtr; async: BOOLEAN) : OSErr; 
ParmBlkPtr; async: BOOLEAN) : OSErr; 
ParmBlkPtr; async: BOOLEAN) : OSErr; 
ParmBlkPtr; async: BOOLEAN) : OSErr; 
ParmBlkPtr; async: BOOLEAN) : OSErr; 




Changing Information About Files 


FUNCTION PBGetFInfo (paramBlock: 
FUNCTION PBSetFInfo (paramBlock: 
FUNCTION PBSetFLock (paramBlock: 
FUNCTION PBRstFLock (paramBlock: 
FUNCTION PBSetFVers (paramBlock: 
FUNCTION PBRename (paramBlock: 
FUNCTION PBDelete (paramBlock: 


ParmBlkPtr ; async : BOOLEAN ) 
ParmBlkPtr; async: BOOLEAN) 
ParmBlkPtr; async: BOOLEAN) 
ParmBlkPtr; async: BOOLEAN) 
ParmBlkPtr; async: BOOLEAN) 
ParmBlkPtr; async: BOOLEAN) 
ParmBlkPtr; async: BOOLEAN) 


OSErr ; 
OSErr; 
OSErr ; 
OSErr; 
OSErr; 
OSErr; 
OSErr ; 


Assembly-Language Information 




Constants 


ioQElSize 
ioFQElSize 
ioVQElSize 
fsQType 
£ Has Bundle 
f Invisible 


EQU 

50 

EQU 

80 

EQU 

64 

EQU 

5 

EQU 

5 

EQU 

6 


;I/0 parameter block size 

;file information parameter block size 

;volume information parameter block size 

; I/O request queue entry type 

;file has a bundle 

;file is invisible 


Structure of Information Used by the Finder 


fdType 

fdCreator 

fdFlags 

fdLocation 

fdFldr 


Type of file 
Creating program 
Flags 

File's location in folder 
Window containing the file 




Standard Parameter Block Data Structure 


ioLink 

ioType 

ioTrap 

ioCmdAddr 

ioCompletion 

ioResult 

ioFileName 

ioVNPtr 

ioVRefNum 

ioDrvNum 


Next queue entry 
Always fsQType 
Routine trap 
Routine address 
Completion routine 
Result code 

File name (and possibly volume name too) 
Volume name 

Volume reference number 
Drive number 
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I/O Parameter Block Data Structure 


ioRefNum 

ioFlleType 

ioPermssn 

ioNewName 

ioLEOF 

ioOwnBuf 

ioNewType 

ioBuffer 

ioReq Count 

ioAct Count 

loPosMode 

ioPosOffset 


Path reference number 

Version number 

Read/write permission 

New file or volume name for Rename 

Logical end -of -file for SetEOF 

Access path buffer 

New version number for SetFilType 

Data buffer 

Requested number of bytes 
Actual number of bytes 

Newline character and type of positioning operation 
Size of positioning offset 


File Information Parameter Block Data Structure 


ioRefNum 

ioFileType 

ioFDir Index 

ioFlAttrib 

ioFFIType 

ioFlUsrWds 

ioFFINum 

ioFIStBIk 

ioFILgLen 

ioFIPyLen 

ioFIRStBIk 

ioFIRLgLen 

ioFIRPyLen 

ioFICrDat 

ioFlMdDat 


Path reference number 
Version number 
File directory index 
File attributes 
Version number 

Information used by the Finder 
File number 

First allocation block of data fork 
Logical end-of-fork of data fork 
Physical end-of-fork of data fork 
First allocation block of resource fork 
Logical end-of-fork of resource fork 
Physical end-of-fork of resource fork 
Date and time file was created 
Date and time file was last modified 


Volume Information Parameter Block Data Structure 


ioVolIndex 

loVCrDate 

ioVLsBkUp 

ioVAtrb 

ioVNmFls 

ioVDirSt 

ioVBILn 

ioVNmAlBlks 

ioVAlBlkSiz 

ioVClpSiz 

ioAlBISt 

ioVNxtFNum 

ioVFrBlk 


Volume index number 

Date and time volume was initialized 

Date and time of last volume backup 

Bit 15=1 if volume is locked 

Number of files in file directory 

First block of file directory 

Number of blocks in file directory 

Number of allocation blocks on volume 

Number of bytes per allocation block 

Number of bytes to allocate 

First block in volume block map 

Next free file number 

Number of free allocation blocks 
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Macro Names 

Routine name 

InitQueue 

PBMountVol 

PBGetVolInfo 

PBGetVol 

PBSetVol 

PBFlshVol 

PBUnmountVol 

PBOffLine 

PBEject 

PBCreate 

PBOpen 

PBOpenRF 

PBRead 

PBHrite 

PBGetFPos 

PBSetFPos 

PBGetEOF 

PBSetEOF 

PB Allocate 

PBFlshFile 

PBClose 

PBGetFInfo 

PBSetFInfo 

PBSetFLock 

PBRstFLock 

PBSetFVers 

PBRename 

PBDelete 


Macro name 
__InitQueue 
_MountVol 
_GetVolInfo 
_GetVol 
_SetVol 
_FlushVol 
_UnmountVol 
JJffUne 
_Eject 
_Create 
_Open 
_OpenRF 
_Read 
_Write 
jGetFPos 
_SetFPos 
jGetEOF 
_SetEOF 
_A1 locate 
_FlushFile 
_Close 
jGetFilelnfo 
_SetFileInfo 
_SetFilLock 
JRstFilLock 
jSetFilType 
_Rename 
Delete 




System Globals 


Name 

fsQHdr 

vcbQHdr 

defVCBPtr 

fcbSPtr 

tagData + 2 

drvQHdr 

toExtFS 


Size 
4 bytes 
4 bytes 
4 bytes 
4 bytes 
4 bytes 
4 bytes 
4 bytes 


Contents 

Pointer to I/O request queue 

Pointer to volume-control-block queue 

Pointer to default volume control block 

Pointer to file-control-block buffer 

Location of file tags 

Pointer to drive queue 

Pointer. to external file system 


Result Codes 


Name 

badMDBErr 

bdNamErr 

dirFulErr 


Value Meaning 

-60 Master directory block is bad; must 

reinitialize volume 

-37 Bad file name or volume name (perhaps zero 

length) 

-33 File directory full 
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dskFulErr 

-34 

All allocation blocks on the volume are full 

dupFNErr 

-48 

A file with the specified name already 
exists 

eofErr 

-39 

Logical end-of-file reached during read 
operation 

extFSErr 

-58 

External file system; file-system identifier 
is nonzero, or path reference number is 
greater than 1024 

fBsyErr 

-47 

One or more files are open 

fLckdErr 

-45 

File locked 

fnfErr 

-43 

File not found 

fnOpnErr 

-38 

File not open 

fsRnErr 

-59 

Problem during Rename 

ioErr 

-36 

Disk I/O error 

mFulErr 

-41 

System heap is full 

noErr 

0 

No error 

nsDrvErr 

-56 

Specified drive number doesn't match any 
number in the drive queue 

noMacDskErr 

-57 

Volume lacks Macintosh-format directory 

nsvErr 

-35 

Specified volume doesn't exist 

opWrErr 

-49 

The read/write permission of only one 
access path to a file can allow writing 

paramErr 

-50 

Parameters don't specify an existing 
volume, and there's no default volume 

permErr 

-54 

Read/write permission doesn't allow writing 

posErr 

-40 

Attempted to position before start of file 

rfNumErr 

-51 

Reference number specifies nonexistent 
access path 

tmfoErr 

-42 

Only 12 files can be open simultaneously 

volOffLinErr 

-53 

Volume not on-line 

volOnLiaErr 

-55 

Volume specified is already mounted and 
on-line 

vLckdErr 

-46 

Volume is locked by a software flag 

wrPermErr 

-61 

Read/write permission or open permission 
doesn't allow writing 

wPrErr 

-44 

Volume is locked by a hardware setting 
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GLOSSARY 

access path: A description of the route that the File Manager follows 
to access a file; created when a file is opened* 

access path buffer: Memory used by the File Manager to transfer data 
between an application and a file* 

allocation block: Volume space composed of an integral number of 
logical blocks. 

asynchronous execution: During asynchronous execution of a File 
Manager routine, the calling application is free to perform other 
tasks* 

block map: See volume allocation block map. 

closed file: A file without an access path. Closed files cannot be 
read from or written to* 

completion routine: Any application-defined code to be executed when 
an asynchronous call to a File Manager routine is completed. 

data buffer: Heap space containing information to be written to a file 
from an application, or read from a file to an application. 

data fork: The part of a file that contains data accessed via the File 
Manager. 

default volume: A volume that will receive I/O during a File Manager 
routine call, whenever no other volume is specified. 

drive number: A number used to identify a drive. The internal drive 
is number 1, and the external drive is number 2. 

drive queue: A list of disk drives connected to the Macintosh. 

end-of-filer See logical end-of-file or physical end-of-file. 

file: A named, ordered sequence of bytes; a principal means by which 
data is stored and transmitted on the Macintosh. 

file directory: The part of a volume that contains descriptions and 
locations of all the files on the volume. 

file I/O queue: A queue containing parameter blocks for all I/O 
requests. 

file name: A sequence of up to 255 characters that identifies a file. 

file number: A unique number assigned to a file, which the File 
Manager uses to distinguish it from other files on the volume. A file 
number specifies the entry of the file in a file directory. 
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file tags: Information associated with each logical block, designed to 
allow reconstruction of files on a volume whose directory or other 
file-access information has been destroyed* 

fork: One of the two parts of a file; see data fork and resource fork. 

file control block: 30 bytes of system heap space in a file - control- 
block buffer containing information about an access path. 

file-control-block buffer: A 362-byte nonrelocatable block containing 
one file control block for each access path* 

format a volume: To write information on the volume that will be read 
by the Disk Driver. 

I/O request: A request for input from or output to a file; caused by 
calling a File Manager routine asynchronously. 

locked file: A file that cannot be written to or deleted. 

locked volume: A volume that cannot be written to or renamed. Volumes 
can be locked by either a software flag or a hardware setting. 

logical block: 512 consecutive bytes on a volume or in memory. 

logical end— of— file: The position of the last byte in a file; equal to 
the actual number of bytes in the file. 

mark: The position of the next byte in a file that will be read or 
written. 

master directory block: Part of the data structure of a volume; 
contains the volume Information and the first 448 bytes of the block 
map. 

mounted volume: A volume that previously was inserted into a disk 
drive and had descriptive information read from it by the File Manager. 

newline character: Any ASCII character, but usually Return (ASCII code 
$0D), that indicates the end of a sequence of bytes. 

newline mode: A mode of reading data where the end of the data is 
indicated by a newline character (and not by a specific byte count). 

off-line volume: A mounted volume with all but 94 bytes of its 
descriptive information deallocated. 

on-line volume: A mounted volume with its volume buffer and 
descriptive information contained in memory. 

open file: A file with an access path. Open files can be read from 
and written to. 
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open permission: Information about a file that indicates whether the 
file can be read from, written to, or both* 

parameter block: Memory space used to transfer information between 
applications and the File Manager* 

path reference number: A number that uniquely identifies an individual 
access path; assigned when the access path is created* 

physical end-of-file: The position of one byte past the last 
allocation block of a file; equal to one more than the maximum number 
of bytes the file can contain* 

read/write permission: Information associated with an access path that 
indicates whether the file can be read from, written to, both read from 
and written to, or whatever the file’s open permission allows* 

resource fork: The part of a file that contains the resources used by 
an application (such as menus, fonts, and icons) and also the 
application code itself; usually accessed via the Resource Manager* 

synchronous execution: During synchronous execution of a File Manager 
routine, the calling application must wait until the routine is 
completed, and isn’t free to perform any other task* 

unmounted volume: A volume that hasn’t been inserted into a disk drive 
and had descriptive information read from it, or a volume that 
previously was mounted and has since had its memory space released* • 

version number: One byte used to distinguish between files with the 
same name* 

volume: A piece of storage medium formatted to contain files; usually 

a disk or part of a disk* The 3 1 /2-inch Macintosh disks are one 
volume* 

volume allocation block map: A list of 12-bit entries, one for each 
allocation block, that Indicate whether the block is currently 
allocated to a file, whether it’s free for use, or which block is next 
in the file* Block maps exist both on volumes and in memory* 

volume attributes: Information contained on volumes and in memory 
indicating whether the volume is locked, has one or more files open (in 
memory only), and whether the volume control block matches the volume 
information (in memory only)* 

volume buffer: Memory used initially to load the master directory 
block; used thereafter for reading from files that are opened without 
their own access path buffer. 

volume control block: A 90— byte nonrelocatable block that contains 
volume-specific information, including the first 64 bytes of the master 
directory block* 
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volume— con trol -block queue: A list of the volume control blocks for 
all mounted volumes* 

volume index: A number Identifying a mounted volume listed in the 
volume -control-block queue* The first volume in the queue has an index 
number of 1 , and so on. 

volume information: Volume-specific Information contained on a volume; 
includes the volume name, number of files on the volume, and so on* 

volume name: A sequence of up to 27 printing characters that 
identifies a volume; always followed by a colon (:) to distinguish it 
from a file name* 

volume reference number: A unique number assigned to a volume as it's 
mounted, used to refer to the volume. 
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See Also: The Macintosh User Interface Guidelines 

Macintosh Operating System Reference Manual 
The Memory Manager: A Programmer's Guide 
QuickDraw: A Programmer's Guide 
The Resource Manager: A Programmer's Guide 
The Window Manager: A Programmer's Guide 
Macintosh Control Manager Programmer's Guide 
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TextEdit: A Programmer's Guide 
Putting Together a Macintosh Application 


Modification History: First Draft (ROM 12) B. Hacker ll/dd/83 


*** REVIEW DRAFT 11/23/83 NOT FOR DISTRIBUTION *** ABSTRACT 

Packages are special file, disk, and mathematical, data structures and 
routines stored as resources. This manual describes packages and the 
Package Manager, the part of the Macintosh User Interface Toolbox that 
provides access to packages. 
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ABOUT THIS MANUAL 

Packages are special -file, disk, and mathematical, data structures and 
routines stored as resources. This manual describes packages and the 
Package Manager, the part of the Macintosh User Interface Toolbox that 
provides access to packages. #** Eventually, it will become part of a 
comprehensive manual describing the entire Toolbox, and Operating 
System. *** 

(eye) 

This manual describes the packages released on 11/17/83, 
which are compatible with version 7 of the ROM. If 
you're using a different version of the packages, the 
^ information presented here may not apply. 

Like all documentation about Toolbox units, this manual assumes you're 
familiar with the Macintosh User Interface Guidelines, Lisa Pascal, the 
Macintosh Operating System's Memory Manager, and the Resource Manager. 
Using the various packages may require that you be familiar with other 
parts of the Toolbox and Operating System too. 

This manual is intended to serve the needs of both Pascal and 
assembly-language programmers. Information of interest to assembly 
language programmers only is isolated and labeled so that Pascal 
programmers can conveniently skip it. 

This manual begins with an introduction to the Package Manager and 
packages and what you can do with them. It then discusses how you use 
the Package Manager to access packages, and describes the Package 
Manager procedures. 

The discussion of the Package Manager is followed by a series of 
sections, each describing one Macintosh package. You'll only need to 
read the sections about the packages that interest you. Each section 
first describes the package briefly and tells how its routines fit into 
the flow of your application program, and then gives detailed 
descriptions of the package's procedures and functions. 

Finally, there's a summary of the Package Manager and the individual 
packages, for quick reference, followed by a glossary of terms used in 
this manual . 


ABOUT THE PACKAGE MANAGER 

The Package Manager is part of the Macintosh User Interface Toolbox 
that gives you access to packages . Packages are a set of less commonly 
used utility data structures and routines stored as resources. The 
standard Macintosh packages are stored in the system resource file, and 
include: 


I 
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~ the Oisk Formatting Package, which enables you to easily format a 
volume, verify a volume, remove information from a volume, or 
handle errors that occur while a volume is being mounted 

- the Standard File Package, which provides a consistent user 
interface for applications to present when a user is to select a 
file to be opened or closed 

*** more to be added *«« 

Each package has its own data structures and routines, and can be used 
independently of the other packages. Packages are resources, with 
resource type PACK and resource IDs B through 7: 


Resource ID 
B 
1 
2 

3 

4 

5 

6 

7 


Package 

*** to be added *** 

**# to be added *** 
Disk Formatting 
Standard File 
see to be added see 
see to be added *** 
ee* to be added see 
see to be added «se 




Before using the Package Manager, you should initialize QuickDraw, the 
File Manager, the Window Manager, the Menu Manager, and TextEdit, in 
that order. 

Before each package can be used, a handle for its resource must be read 
into memory. You can call the Package Manager procedure InitPack to 
get a handle to a single package, or the procedure InitMath to get 
handles to all the packages at once. After the handle to a package has 
been read into memory, the package itself can be called. 


PROCEDURE InitPack <packNumbers INTEGER); 

InitPack gets a handle to the package specified by packNumber, which is 
simply the package's resource ID. 


PROCEDURE InitMath; 

InitMath gets handles to all packages as though InitPack were called 
repeatedly with packNumbers B through 7. *** The name of this 

procedure will change sx« 

Each of the packages is described individually in the following 
sections, and you need only read the sections about packages that 
interest you. 
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THE DISK FORMATTING PACKAGE 

The Disk Formatting Package allows you to: 

- ■format a volume 

- verify the information on a volume 

- remove information from a volume 

- handle errors that occur while a volume is being mounted 

To use the Formating Package effectively, you'll need to be familiar 
with: 

- the Package Manager 

- the File Manager #** up-to-date documentation about the File 

Manager isn't available, but see the File System Core Routines and 
File and I/O Core Routines sections of the Macintosh OS Reference 
Manual . *#* 

- QuickDraw, particularly the data type ’Point* 

- the Toolbox Event Manager 


Using the Disk Formatting Package 

To use the Disk Formatting Package, first you must call the Package 
Manager with Ini tPack<2) or InitMath, and then call FmtLoad, which 
reads the package into memory. When you're through using the package, 
call FmtUnload, which makes it purgeable. 

To format a volume, call FmtFormat, which writes special information 
onto the volume for the Disk Driver to read. To verify a volume, call 
FmtVerify, which verifies that each block on the volume can be read 
without an ioErr being returned. To remove all information stored on a 
volume, call FmtZero, which writes new volume information, a new block 
map, and a new file directory onto the volume. 

Whenever the File Manager returns an error number while attempting to 
mount a volume, you should call FmtBadMnt and have the Disk Formatting 
Package handle the situation. If the error number indicates a 
memFullErr, paramErr, volOnLinErr, extFSErr, or nsDrvErr, the disk is 
ejected and control returns to the application. 

(hand) 

ParamErr, volOnLinErr, extFSErr, and nsDrvErr, properly 
should be handled by your application and not passed to 
FmtBadMn t . 
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If the error number indicates an ioErr, a badMDBErr, or a noMacDsKErr, 
FmtBadMnt allows the user to either -format or eject the disk. 


Disk Formatting Package Routines 


PROCEDURE FmtLoad; 

FmtLoad reads the Disk Formatting Package into memory and marks it as 
nonpurgeable. You must call this routine before calling any of the 
others in this package. 


Assembl y-1 anouaoe note 5 The macro you invoke to call FmtLoad 
from assembly language is named _Pack2. 


PROCEDURE Frot Unload} 

FmtUnload marks the Disk Formatting Package as purgeable. 


FUNCTION FmtFormat (drvNumt INTEGER) : INTEGER} 

FmtFormat formats the volume in the drive specified by drvNum, and 
returns 0 if the formatting was completed successfully, or a File 
Manager error number if it failed. Formatting a volume consists of 
writing special information onto the volume for the Disk Driver to 
read. 


FUNCTION FmtVerify (drvNumt INTEGER) s INTEGER; 

FmtVerify reads each block from the volume in the drive specified by 
drvNum, and returns 0 if each bit in each block was read successfully, 
or a File Manager error number if any bit was unreadable. 


FUNCTION FmtZero (drvNum* INTEGER) s INTEGER; 

FmtZero writes new volume information, a new block map, and a new file 
directory onto the volume in the drive specified by drvNum, and returns 
0 if the operation was completed successfully, or a File Manager error 
number if the operation failed. 
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FUNCTION FmtBadMnt (where t Point; evtMessage: Longlnt) s INTEGER; 

FmtBadlnt evaluates the error message passed to it in the high-order 
word of evtMessage, and either ejects the disk from the drive indicated 
by the low-order word of evtMessage, or displays an dialog box whose 
top left corner is at the location specified in global coordinates by 
the where parameter. The value of evtMessage should be taken from an 
event record for a disk inserted event. 

If the error number passed corresponds to memFul lErr , paramErr , 
volOnLinErr, extFSErr, or nsDrvErr, the disk is ejected and control 
returns to the application. If an ioErr, badMDBErr, or noMacDskErr , is 
passed, FmtBadMnt displays the dialog box shown in Figures 1, 2, or 3, 
respectively. 


F i gure I . i oErr Dialog 


Figure 2. BadMDBErr Dialog 
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Figure 3. NoMaeDskErr Dialog 

If the user responds by clicking the Eject button, the disk is ejected 
and control returns to the application. It the Initialize button is 
clicked, the dialog box in Figure 4 is displayed and the volume is 
-formatted and verified <to the user, formatting is called 
8 i n i t i al i z i ng 8 ) . 


Figure 4. Disk Initialization Dialog 

If either the formatting or the verification fails, the user is 
informed as shown in Figure 5} after the user clicks the Continue 
button a File Manager error number is returned as the function's 
result, the disk is ejected, and controls returns to the application. 


Figure 5. Initialization Failure Dialog 

If the volume is successfully formatted, the dialog box in Figure 6 
allows the user to name the volume. 
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Figure 6 . Dialog -for Naming a Volume 

After the user names the uolume and clicks OK, control returns to the 
appl ication. 


THE STANDARD FILE PACKAGE 

The Standard File Package consists of two routines that provide a 
consistent user interface for applications to present when opening or 
closing files on a volume. You should already be familiar with the 
following to use the Standard File Package effectively; 

- the File Manager 

- the Dialog Manager 

- the Resource Manager, particularly resource types 

- the QuickDraw data type "Point" 


Using the Standard File Package 

To use the Standard File Package, first you must call the Package 
Manager with Ini tPack<3) or InitMath. The Standard File Package is 
automatically read into memory when either of its routines is called. 

Whenever your application must ask the user to specify s file to which 
a Save command should be applied, call SFPutFile, which displays a 
dialog box allowing the user to enter the file's name. A-Mer the user 
has entered a name, SFPutFile determines whether the Save can be 
applied to the specified file, and returns the answer to your 
appl ication . 

Whenever your application must ask the user to choose one file to be 
opened from a list of files, call SFGetFile, which displays a dialog 
box with the list of choices. After the user has made a choice, 
SFGetFile determines whether the file can be opened, and then returns 
the answer to your application. 
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PROCEDURE SFPutFi 1 e (where: Point; prompts Str255; fileName: Str2S5; 
dlgHooks ProcPtr; MAR repl/List: SFReplyPtr); 

SFPutFi le displays a dialog box allowing the user to specify a file to 
which a Save command should be applied. After the user enters a file 
name, SFPutFi le determines whether the Save can be applied to the 
specified file, and returns the answer to your application. 

The standard SFPutFile dialog box is shown in Figure 7; note that the 
Drive button won'' t be displayed unless there's an external drive 

connec ts»d to the Macintosh. The volume name shown is initially the 
volume in the internal drive (if there is one), but toggles between 
on-line volumes each time the Drive button is clicked. 


Figure 7. Standard SFPutFile Dialog 

The where parameter specifies the location of the top left corner of 
the dialog box in global coordinates. Prompt points to a line of text 
to be displayed in the dialog box at the position shown in Figure 7. 

The fileNarae parameter contains text that appears as a default file 
name in the dialog box and can be edited in the conventional way. If 
f i 1 eName is NIL, only an insertion point will appear. 

By using the dlgHook parameter, you can determine the appearance and 
function of the dialog box drawn. If you want to use the standard 
SFPutFile dialog box, pass NIL for dlgHook (if not, see the note 
below) . 

After drawing the standard SFPutFile dialog box, SFPutFile repeatedly 
gets and handles events in the dialog's window by using the Dialog 
Manager procedure ModalDialog. All events other than mouse down events 
in buttons are ignored. Every time the user clicks 

- the Drive Button (if it exists), the dialog box is redrawn to show 
the name of the other on-line volume, and SFPutFile again begins 
handling events via ModalDialog 
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- the Eject button, the disk is ejected and SFPutFile again begins 
handling events via ModalDialog 

- the Cancel button, SFPutFile returns control to the application 
along with a pointer, replyList, to a record with the -following 
data structure: 


TYPE SFRepl y = 
cl i eked) 


RECORD 


good: 

BOOLEAN; 

copy: 

BOOLEAN; 

fType : 

ResType ; 

vRefNum : 

INTEGER; 

fName : 

Str255 

END} 



(FALSE if Cancel 

(unused) 

(unused) 

(unused) 

(name of original file) 


SFRepl yPtr = ‘SFReply 


From the SFReply record, your application can determine whether 
the Save command should be ignored or if the file named fName 
should be saved with the name fileName. 


- the Save button, SFPutFile determines whether the Save can be 
applied to the specified file. If the volume to which the file 
should be written is write-protected, the alert shown in Figure 8 
is displayed. The alert in Figure 9 is displayed if there already 
exists a file with the name fileName. If the user includes a 
volume prefix in fileName, and the volume doesn't exist, the alert 
in Figure 10 is displayed. The alert in Figure 11 is displayed if 
a system error occurs. 


After the user clicks a No or Cancel button in response to an 
alert, SFPutFile again begins handling events via ModalDialog. If 
the user clicked a Yes button or if no a’ert was displayed, 
SFPutFile returns control to the application along with a pointer 
to an SFReply record. 


Figure 8. Write-Protect Alert 
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Figure 9. Alert -for Existing File 




Figure 10. Alert -for Nonexistent Disk 


Figure 11. System Error Alert 


Advanced programmers; If you don't want to use the standard SFPutFile 
dialog box, and instead you want to create your own dialog, you must 
provide your own dialog template, and store it in your application's 
resource file with the same resource type and resource ID, that it is 
stored with in the system resource file <the Resource Manager searches 
your application's resource file before it searches the system resource 
file, and will load your dialog template instead of the system resource 
file's dialog template). If your new dialog box has different dialog 
items than the standard SFPutFile dialog box or if you want to handle 
any of the standard SFPutFile dialog items in a nonstandard manner, you 
must write your own dlgHook function to do so, and point to it with 
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dlgHook. Your dlgHook -function should have two parameters and return 
an integer value. For example, this is how it would be declared if it 
were named MyDlg: 

FUNCTION MyDlg (item: INTEGER; dialogs DialogPtr): INTEGER 

Instead of handling all mouse down events as described above, SFPutFile 
passes information about every event in an enabled dialog item to your 
dlgHook function. In the dialog parameter it passes a pointer to the 
dialog record describing your dialog box, and in the item parameter it 
passes the item number of the item. Using these two parameters, your 
dlgHook function should determine how to handle the event (probably by 
calling the Di al og Manager function GetDItem). After handling the 
event (or, perhaps, after ignoring it) your dlgHook function must 
return an item number to SFPutFile. If the item number corresponds to 
one of the buttons in the standard SFPutFile dialog: 

Item number Button 

1 Save 

2 Cancel 

5 Eject 

6 Drive 

SFPutFile will perform as described above. If the item number doesn't 
correspond to one of these four numbers, SFPutFile again begins 
handling events via ModalDiatog. 


PROCEDURE SFGetFi le (where: Point; prompt: Str255; filter: ProcPtr ; 

numTypes: INTEGER; typeLists SFListPtr; dlgHook: Ptr; YAR 
replyList: SFReplyPtr); 

SFGetFi le displays a dialog box listing the names of a specific group; 
of files from which the user can select one file to be opened. After 
the user selects a file, SFGetFile determines whether the file can be 
opened, and then returns the answer to your application. 

The standard SFGetFile dialog box is shown in Figure 12; note that the 
Drive button won't be displayed unless there's an external drive 
connected to the Macintosh. The volume name shown is initially the 
default volume (if there is one), but toggles between on-line volumes 
each time the Drive button is clicked. 
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Figure 12. Standard SFGetFile Dialog 

The where parameter specifies the location of the top left corner of ^ 

the dialog box in global coordinates. Prompt points to a line of text 
to be displayed in the dialog box at the position shown in Figure 12. 

By using the filter parameter or the numTypes and typeList parameters* 
you can determine which files appear in the dialog box (for example, if 
the application were concerned only with pictures, you wouldn't want to 
display the names of any text files). If you want all files on the 
volume to appear in the dialog, pass NIL for filter and -1 for 
numTypes. 

If numTypes isn't NIL, SFGetFile uses typeList and numTypes to 
determine which files appear in the dialog. TypeList contains a 
pointer to a list of file types (which are the same as resource types), 
and numTypes indicates the number of file types in typeList: 

TYPE SFTypeList = ARRAY EB. .numTypes) OF ResType; 

SFTLi stPtr = ‘SFTypeList 




(hand) 

The variable-length array shown isn't correct Pascal 
syntax, and is used only as a conceptual aid. 

Every file whose file type is included in typeList will be shown in the 
dialog. 

If filter isn't NIL, SFGetFile uses a filter function pointed to by the 
filter parameter to determine which files appear in the dialog. The. 
filter function has one parameter and returns a boolean value. For 
example, this is how it would be declared if it were named 
MyFi leFi 1 ter: 

FUNCTION MyFi leFi 1 ter (flnfo: Filelnfo) : BOOLEAN 

SFGetFile passes the file directory information (which it gets by 
calling the File Manager procedure GetFilelnfo) for every file on the 
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volume, to the -filter -function, one -file at a time. The -filter 
-function can select which -files appear in the dialog by using any part 
of the information in the flnfo record *** not yet explicitly defined 
as "filelnfo* in any manual, but is the information returned by a File 
Manager GetFilelnfo procedure »##, and returning FALSE for every file 
that should be shown, and TRUE for every file that shouldn't be shown 
in the list. 


By using the dlgHook parameter, you can determine the appearance and 
function of the dialog box drawn. If you want to use the standard 
SFGetFile dialog box, pass NIL for dlgHook <if not, see the note 
below). After drawing the standard SFGetFile dialog box, SFGetFile 
repeatedly gets and handels events in the dialog's window by using the 
Dialog Manager procedure Modal Dialog. All events other than mouse down 
events are ignored. Every time the user clicks 


- the Drive button <if it exists), the dialog box is redrawn to show 
the name of the other on-line volume, and SFGetFile again begins 
handling events via ModalDialog 


the Eject button, the disk is ejected and SFGetFile again begins 
handling events via ModalDialog 

in the scroll bar or scroll arrows, the contents of the dialog box 
are redrawn accordingly, and SFGetFile again begins handling 
events via ModalDialog 


the Cancel button, SFGetFile returns control to the application 
along with a pointer, replyList, to a record with the following 
data structure: 


TYPE SFReply * 

RECORD 



good: 

BOOLEAN: 

cl icked) 


copy: 

BOOLEAN? 


fType : 

ResType ; 

selected) 


vRefNum: 

INTEGER; 

number) 


fName : 

Str255 


END; 


(FALSE if Cancel 
(unused) 

(file type of file 
(volume reference 
(name of original file) 


SFRepl yPtr =» ‘SFReply 

From the SFReply record, your application can determine whether 
the Open command should be ignored or if the file named (Name on 
the volume spcified by vRefNum should be opened, and titled 
f i 1 eName . 


a file name, followed by the Open button, SFGetFile determines 
whether the Open can be applied to the specified file. If the 
user includes a volume prefix in fiieName, and the volume doesn't 
exist, the alert in Figure 1# above is displayed., If any other 
system error occurs, the alert in Figure 11 is displayed. 
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After the user clicks the Cancel button in response to an alert, 
SFGetFile again begins handling events via ModalDialog. If no 
alert was displayed, SFGetFile returns control to the application 
along with a pointer to an SFReply record. 

Advanced programmers: If you don't want to use the standard SFGetFile 
dialog box, and instead you want to create your own dialog, you must 
provide your own dialog template, and store it in your application's 
resource file with the same resource type and resource ID that it is 
stored with in the system resource file <the Resource Manager searches 
your application's resource file before it searches the system resource 
file, and will load your dialog template instead of the system resource 
file's dialog template). If your new dialog box has different dialog 
items than the standard SFGetFile dialog box or if you want to handle 
any of the standard SFGetFile dialog items in a nonstandard manner, you 
must write your own dlgHook function to do so, and point to it with 
dlgHook. Your dlgHook function should have two parameters and return 
an integer value. For example, this is how it would be declared if it 
were named MyDIg: 

FUNCTION MyDlg (item: INTEGER} dialog: DialogPtr): INTEGER 

Instead of handling all mouse down events as described above, SFGetFile 
passes information about every event in an enabled dialog item to your 
dlgHook function. In the dialog parameter it passes a pointer to the 
dialog record describing your dialog box, and in the item parameter it 
passes the item number of the item. Using these two parameters, your 
dlgHook function should determine how to handle the event (probably by 
calling the Dialog Manager function GetDItem). After handling the 
event (or, perhaps, after ignoring it) your dlgHook function must 
return an item number to SFGetFile. If the item number corresponds to 
one of the controls in the standard SFGetFile dialog: 


Item number 
1 
2 
3 
5 

6 

7 

8 


Control 
Open button 
Open copy button 
Cancel button 
Eject button 
Drive button 
File name text 
Scroll bar 


SFGetFile will perform as described above. If the item number doesn't 
correspond to one of these four numbers, SFGetFile again begins 
handling events via ModalDialog. 
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SUMMARY OF THE PACKAGE MANAGER 

PROCEDURE InitPack (packNuraber : INTEGER); 
PROCEDURE InitMath; 


SUMMARY OF THE DISK FORMATTING PACKAGE 


Data Structures 

TYPE SFRepl y ■ RECORD 

good : BOOLEAN ; 
copy: BOOLEAN; 

■fType: ResType; 

uRe-fNum: INTEGER; 

-fName: Str255 

END; 

SFRepl yPtr * ‘SFRepl y; 

SFTypeList = ARRAY CE..10] OF ResType; 

SFTListPtr * ‘SFTypeList 


Rout i nes 




PROCEDURE FmtLoad; 
PROCEDURE FmtUnload; 
FUNCTION Fmt Format 
FUNCTION FmtVer i-fy 
FUNCTION FmtZero 
FUNCTION FmtBadMnt 


(drvNum: INTEGER) : INTEGER; 

(drvNum: INTEGER) : INTEGER; 

(drvNum: INTEGER) : INTEGER; 

(where: Point; eutMessage: Longlnt) : INTEGER; 


SUMMARY OF THE STANDARD FILE PACKAGE 


Rout i nes , 

PROCEDURE SFPutFile (where: Point; prompt: Str255; fileName: 

Str255; dlgHook: ProcPtr; VAR replyList: 
SFRepl yPtr ) ; 

PROCEDURE SFGetFile (where: Point; prompt: Str255; -filter: 

ProcPtr; numTypes: INTEGER; typeList: 
SFListPtr; dlgHook: Ptr; VAR replyList: 
SFRepl yPtr) ; 

FUNCTION MyDlg (item: INTEGER; dialog: DialogPtr) : INTEGER; 

FUNCTION MyFileFilter (fln-fo: Fileln-fo) : BOOLEAN 
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Assembly-Language Information 


Reply Record Data Structure 


rGood 
rType 
r Volume 
rName 


FALSE i-f Cancel button clicked 
File type o-f -file (SFGetFile only) 

Volume re-ference number (SFGetFile only) 
Name o-f original -file 
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GLOSSARY 

•filter 'function: a function that filters files based upon directory 
information about the files. 

package: special file, disk, and mathemat i cal , data structures and 
routines stored as resources. 
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The Device Manager: A Programmer's Guide 
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See Also: The Macintosh User Interface Guidelines 

The Memory Manager: A Programmer's Guide 
The File Manager: A Programmer's Guide 
The Desk Manager: A Programmer's Guide 
Inside Macintosh: A Road Map 


Modification History: First Draft (ROM 7) B. Hacker 2/dd/84 


*** Review Draft. Not for distribution *** ABSTRACT 

This manual describes the Device Manager, the part of the Macintosh 
Operating System that controls the exchange of information between a 
Macintosh application and devices. 
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ABOUT THIS MANUAL 

This manual describes Che Device Manager, Che pare of Che MaclnCosh 
Ope racing SysCem “hat conCrols Che exchange of InformaClon beCween a 
MaclnCosh applicacion and devices, *** EvenCually ie will become pare 
of a larger manual describing Che end re Toolbox and OperaCing SysCem. 
*** General InformaClon abouC using device drivers can be found in Chis 
manual; specific InformaClon abouC Che sCandard MaclnCosh drivers Is 
conealned In separaCe manuals. 

(eye) 

This manual describes version 7 of Che ROM. If you're 
using a differenC version, Che Device Manager may noC 
work as discussed here. 

Like all OperaCing SysCem documencaclon, this manual assumes you're 
familiar wlch Lisa Pascal. You should also be familiar wlch Che 
following: 

- Che basic concepCs behind Che MaclnCosh OperaCing SysCem' s Memory 
Manager 

- applicaClon daCa buffers, as described in Che MaclnCosh OperaCing 
SysCem 's File Manager manual 

The manual Is InCended Co serve Che needs of boch Pascal and 
assembly-language programmers. InformaClon of inCeresC Co assembly- 
language programmers only is IsolaCed and labeled so ChaC Pascal 
programmers can conveniently skip it. 

This manual begins with an introduction to the Device Manager and what 
you can do with it. It Chen discusses some basic concepCs behind Che 
Device Manager: what devices and drivers are, and how they are used. 

A section on using the Device Manager introduces its routines and Cells 
how they fit into the flow of your application. This is followed by 
detailed descriptions of all the procedures and functions used to call 
device drivers, their parameters, calling protocol, effects, side 
effects, and so on. 

Following these descriptions are sections that provide information for 
programmers who want to write their own drivers, including a discussion 
of interrupts and a sample driver. 

Finally, there's a summary of the Device Manager, for quick reference, 
followed by a glossary of terms used in this manual. 
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ABOUT THE DEVICE MANAGER 

The Device Manager Is the part of the Operating System that handles 
communication between applications and devices* A device Is a part of 
the Macintosh, or a piece of external equipment, that can transfer 
information Into or out of the Macintosh* Macintosh devices include 
the keyboard, screen, disk drives, two asynchronous serial ports, the 
sound generator, the mouse, and printers* 

There are two kinds of devices: character devices and block devices* 

A character device reads or writes a stream of characters, one at a 
time: it can neither skip characters nor go back to a previous 
character* A character device Is used to get Information from or send 
information to the world outside of the Macintosh Operating System and 
memory: it can be an Input device, an output device, or an 
Input/output device. The mouse, keyboard, screen, sound generator, and 
printers, are all character devices. 

A block device reads and writes blocks of 512 characters at a time; it 
can read or write any accessible block on demand. A block device is 
used to store and retrieve Information: it's always an Input/output 
device. Disk drives are block devices* 

Applications communicate with devices by calling Device Manager 
routines* The Device Manager routines don't manipulate devices, but 
they call device drivers that do. Device drivers are programs that 
take streams or blocks of characters coming from the Device Manager and 
convert them into actions of devices, and convert device actions into 
streams or blocks of characters for the De.vlce Manager to process. 

All Information exchange between the Device Manager and devices occurs 
via drivers; the Device Manager never communicates directly with a 
device (see Figure 1). 



Figure 1* Communication with Devices 

The Operating System Includes three standard device drivers in ROM: 
the Disk Driver, the Sound Driver, and the Serial Driver. There are 
also a number of standard RAM drivers that are read from the system 
resource file when the system starts up: the Printer Driver and desk 
accessories* The keyboard and mouse don't have drivers, and are 
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handled via the Keyboard/Mouse Handler* Other drivers can be added 
independently or built on the existing drivers (for example, the 
Printer Driver is built on top of the Serial Driver); the section 
"Writing Your Own Device Drivers" describes how to do this* Desk 
accessories are a special type of device driver, in that they have 
windows, their name should appear in the Apple menu, and they are 
manipulated via the specialized routines of the Desk Manager. 
Information about desk accessories covered in the Desk Manager manual 
will not be repeated here. 

A driver can be either open or closed . After a driver has been opened, 
an application can read Information from and write information to the 
driver. Drivers that are no longer in use can be closed, and the 
memory used by them recovered. The standard Macintosh drivers are 
opened when the system starts up. Up to 32 drivers may be open at any 
one time. 

A driver is identified by its driver name and, after it's opened, by 
its reference number. A driver name consists of a period (.) followed 
by any sequence of 1 to 255 printing characters. You can use uppercase 
and lowercase letters when naming drivers, but the Device Manager 
ignores case when comparing names (it doesn't ignore diacritical 
marks ) . 

(hand) 

Although driver names can be quite long, there's little 
reason for them to be more than a few characters in 
length. Normally the user will never see a driver name 
unless it's displayed in a menu, and names in menus 
should be short enough that the menu doesn ' t become 
excessively wide. 

The Device Manager assigns each open driver a driver reference number , 
from —1 to “32, that is used Instead of its driver name to refer to it. 

In addition to data that's read from or written to drivers, drivers may 
require or provide other information. Required information transmitted 
to a driver by an application is called control information ; 
information provided by a driver is called status information . Control 
information may select modes of operation, start or stop processes, 
enable buffers, choose protocols, and so on. Status information may 
indicate the current mode of operation, the readiness of the device, 
the occurrence of errors, and so on. 
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Each driver nay respond to a number of different types of control 
information and may provide a number of different types of status 
information* The standard Macintosh drivers receive control 
Information and provide status Information via a predefined data 
structure, of type OpParamType: 

TYPE OpParamPtr - ^OpParamType ; 

OpParamType - RECORD 

CASE OpVariant OF 

{control information} 

sound: {Sound Driver} 

(sndVal: INTEGER); 

asyncRst: {Async Driver} 

( asncConf ig : INTEGER) ; 
asynclnBuff : 

(asncBPtr: Ptr; 
asncBLen: INTEGER); 
asyncShk: 

(asncHndShk: Long In t; 
asncMisc: Longlnt); 

printer: {Printer Driver} 

(paraml: Longlnt; 
param2: Longlnt; 
param3: Longlnt); 

fontMgr: {Font Manager} 

(fontRecPtr: Ptr; 
fontCurDev: INTEGER); 
diskDrv: {Disk Driver} 

(diskBuff: Ptr); 

{status information} 

asyncBuff Bytes : {Async Driver} 

(asyncNBytes: Longlnt); 
asyncStatus: 

(asncSl: INTEGER; 
asncS2: INTEGER; 
asncS3: INTEGER); 

diskStat: {Disk Driver} 

(dskTrackLock: INTEGER; 
dsklnfoBits: Longlnt; 
dskQElem: drvrQElRec; 

dskPrime: INTEGER; 

dskErrCnt: INTEGER); 

END; 

The CASE statement selects which field(s) of the record will be used, 
based on the OpVariant data type: 

TYPE OpVariant « (sound, asyncRst, asynclnBuff, asyncShk, printer, 

fontMgr, diskDrv, asyncBuff Bytes, asyncStatus, 
diskStat) ; 

The maximum size of the OpParamType variant record is 22 bytes* 
Explanations of the fields can be found in the manuals describing the 
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different drivers* 


USING THE DEVICE MANAGER 


This section discusses how the Device Manager routines fit into the 
general flow of an application program and gives an idea of what 
routines you'll need to use. The routines themselves are described in 
detail in the next section. 

The Device Manager routines can be called via three different methods: 
high-level Pascal calls, low-level Pascal calls, and assembly language. 
The high-level Pascal calls are designed for Pascal programmers 
Interested in using the Device Manager in a simple manner; they provide 
adequate device I/O and don't require much special knowledge to use. 

The low-level Pascal and assembly— language calls are designed for 
advanced Pascal programmers and assembly— language programmers 
interested in using the Device Manager to its fullest capacity; they 
require some special knowledge to be used most effectively. 

(hand) 

The names used to refer to routines here are actually 
assembly-language macro names, but the Pascal routine 
names are very similar. 

The Device Manager is automatically initialized each time the system is 
started up. 

Before an application exchanges information with a driver, the driver 
must be opened. ROM drivers are opened when the system starts up; for 
RAM drivers, call Open. (Desk accessories use OpenDeskAcc. ) The 
Device Manager will return the driver reference number that you'll use 
every time you want to refer to that driver. 

You can transfer data from an open driver to an application's data 
buffer with Read, and send data from an application's data buffer to a 
driver with Write. An application passes control information to a 
driver by calling Control, and receives status Information from a 
driver by calling Status. 

Whenever you want to stop a driver from completing I/O initiated by a 
Read, Write, Control, or Status call, call KilllO. KilllO halts the 
currently executing I/O, and ignores any pending I/O (if any). 

When you're through using a driver, call Close. (Desk accessories use 
CloseDeskAcc. ) Close forces the driver to complete any pending I/O, 
and then deallocates all the memory used by the driver. *** Currently, 
you shouldn't close the Serial Driver. *** 

Advanced programmers who write their own device drivers may find the 
Desk Manager routines SystemClick, SystemEdlt, and SystemTask to be of 
use. 
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DEVICE MANAGER ROUTINES 

This section Is divided into three parts that describe routines used to 
call drivers* The first presents the two routines used to open and 
close drivers; this part must be read by all programmers* The 
second describes all the high-level Pascal routines of the Device 
Manager, and the third presents Information about calling the low-level 
Pascal and assembly-language routines* 

All Device Manager routines return a result code of type OSErr* Each 
routine description lists all of the applicable result codes, along 
with a short description of what the result code means* Lengthier 
explanations of all the result codes can be found in the summary at the 
end of this manual* 


Routines For Opening and Closing Drivers 


FUNCTION OpenDriver (name: OSStr255; VAR refNum: INTEGER) : OSErr; 
OpenDrlver opens the driver specified by name and returns its reference 


number in refNum. 

Result codes noErr 
resErr 
badUnitErr 
dSIOCoreErr 
openErr 

unltEmptyErr 


No error 

Resource Manager error 
Bad reference number 
Device control entry was purged 
Driver cannot perform reading 
or writing 

Bad reference number 


FUNCTION CloseDriver (refNum: INTEGER) : OSErr; 

CloseDriver closes the driver having the reference number refNum. Any 
pending I/O is completed, and the memory used by the driver is 
deallocated* 


Result codes noErr 

badUnitErr 

dSIOCoreErr 

resErr 

unltEmptyErr 


No error 

Bad reference number 
Device control entry was purged 
Resource Manager error 
Bad reference number 
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High-Level Device Manager Routines 


FUNCTION FSRead (refNum: INTEGER; VAR count: Longlnt; buffPtr: Ptr) : 
OSErr; 

FSRead attempts to read the number o£ bytes specified by the count 
parameter from the driver having the reference number refNum, and 
transfer them to the data buffer pointed to by buffPtr. After the read 
is completed, the number of bytes actually read is returned In the 
count parameter* 

No error 

Bad reference number 
Device control entry was purged 
Driver isn't open 
Bad reference number 
Driver isn't enabled for read 
calls 


FUNCTION FSWrite (refNum: INTEGER; VAR count: Longlnt; buffPtr: Ptr) : 
OSErr; 

FSWrite attempts to take the number of bytes specified by the count 
parameter from the buffer pointed to by buffPtr and write them to the 
open driver having the reference number refNum. After the write is 
completed, the number of bytes actually written is returned in the 
count parameter. 

No error 

Bad reference number 
Device control entry was purged 
Driver isn't open 
Bad reference number 
Driver isn't enabled for write 
calls 
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FUNCTION FSControl (refNum: INTEGER; opCode: INTEGER; opParams: 

OpParamPtr) : OSErr; 

FSControl sends control Information to the driver having the reference 
number refNum. The type of information sent is specified by opCode, 
and the information Itself is pointed to by opParams. The values 
passed in opCode and pointed to by opParams depend on the driver being 
called. 

Result codes noErr 

badUnitErr 
dSIOCoreErr 
notOpenErr 
unitEmptyErr 
controlErr 


FUNCTION FSStatus (refNum: INTEGER; 

OpParamPtr) : OSErr; 

FSStatus returns status information about the driver having the 
reference number refNum. The type of information returned is specified 
by opCode, and the information Itself is pointed to by opParams. The 
values passed in opCode and pointed to by opParams depend on the driver 
being called. 

Result codes noErr 

badUnitErr 
dSIOCoreErr 
notOpenErr 
unitEmptyErr 
statusErr 


No error 

Bad reference number 

Device control entry was purged 

Driver isn't open 

Bad reference number 

Driver isn't enabled for status 

calls 


No error 

Bad reference number 

Device control entry was purged 

Driver isn't open 

Bad reference number 

Driver isn't enabled for control 

calls 


opCode: INTEGER; opParams : 


FUNCTION FSKilllO (refNum: INTEGER) : OSErr; ^ 

FSKilllO terminates all I/O with the driver having the reference number 
refNum. 


Result codes 

noErr 

No error 



badUnitErr 

Bad reference number 



dSIOCoreErr 

Device control entry was 

purged 


unitEmptyErr 

Bad reference number 



controlErr 

Driver isn't enabled for 
calls 

control 
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Low-Level Device Manager Routines 

This section contains special Information for programmers using the 
low-level Pascal or assembly-language routines of the Device Manager, 
and then describes the routines in detail* 

All Device Manager routines described in this section can be executed 
either synchronously (meaning that the application must wait until the 
routine is completed) or asynchronous lv (meaning that the application 
is free to perform other tasks while the routine is executing). 

When a Device Manager routine is called asynchronously, an I/O request 
is placed in the driver's I/O queue , and control returns to the calling 
application — even before the actual I/O is completed. Requests are 
taken from the queue one at a time (in the same order that they were 
entered), and processed. Only one request may be processed at any 
given time. 

The calling application may specify a completion routine to be executed 
as soon as the I/O operation has been completed. 

Routine parameters passed by an application to the Device Manager and 
returned by the Device Manager to an application are contained in a 
parameter block , which is memory space in the heap or stack. All 
low-level Pascal calls to the Device Manager are of the form 

PBCallName (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 

PBCallName is the name of the routine. ParamBlock points to the 
parameter block containing the parameters for the routine. If async is 
TRUE, the call will be executed asynchronously; if FALSE, it will be 
executed synchronously. 


Assembly-language note : All Device Manager routines are called 
with A 0 pointing to a parameter block containing the parameters 
for the routine, and A1 pointing to the driver's device control 
entry. All routines return with D0 containing a result code. 

You specify whether a routine will be executed synchronously or 
asynchronously by clearing or setting bit 10 of the routine trap 
instruction, as described in the Using Assembly Language manual 
*** doesn't exist yet ***• 
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Routine Parameters ^ 

The lengthy, variable-length data structure of a parameter block is 
given below. The Qgplee’ s 'Maa*ge&--'£hd File Manage r^use* this same data 
structure, but only the parts relevant to the Device Manager are 
discussed here. Each kind of parameter block contains eight fields of 
standard information and two to nine fields of additional information: 

TYPE ParamBlkType » (ioParam, flleParam, volume Par am, controlParam) ; 


ParamBlockRec » RECORD 


ioLink: 

Ptr; 

{next queue entry} 

ioType: 

INTEGER; 

{always 5} 

ioTrap : 

INTEGER; 

{routine trap} 

ioCmdAddr: 

Ptr; 

{routine address} 

loCompletlon: 

ProcPtr; 

{completion routine} 

IoResult : 

OSErr; 

{result code} 

ioNamePtr : 

OSStrPtr; 

{driver name} 

loVRefNum: 

INTEGER; 

{not used} 

CASE ParamBlkType OF 
ioParam: 

... {I/O routine parameters} 


flleParam: 

. . . {file information routine parameters} 
volumeParam: 

... {volume Information routine parameters} 
controlParam: 

. . . {Control and Status routine parameters} 

END; 




ParmBlkPtr = “ParamBlockRec; 

The first four fields in each parameter block are handled entirely by 
the Device Manager, and most programmers needn't be concerned with 
them; programmers who are Interested in them should see the section 
"The Structure of a Driver". 

XOCompletion contains the address of a completion routine to be 
executed at the end of an asynchronous call; it should be NIL for 
asynchronous calls with no completion routine, and is automatically set 
to NIL for all synchronous calls. For asynchronous calls, ioResult is 
positive while the routine is executing, and returns the result code. 

IONamePtr is a pointer to the name of a driver. 

An 8-field parameter block is adequate for opening a driver, but most 
of the Device Manager routines require longer parameter blocks, as 
described below. The parameters used with file and volume information 
routines are described in the File Manager manual. 

Control and Status routines use two additional fields: 
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controlParam: 

csCode: INTEGER; {type of Control or Status call} 
csParam: OpParamType ; {control or status information} 


CSCode contains a number identifying the type of call. This number may 
be Interpreted differently by each driver. CSParam contains the 
control or status Information for the call. 

I/O routines use seven additional fields: 


ioParam: 
ioRefNum: 
loVersNum: 
ioPermssn: 
ioMisc: 
ioBuffer: 
ioReq Count: 
ioAct Count : 
ioPosMode: 
ioPosOffset: 


INTEGER; 
SlgnedByte; 
SignedBy te ; 
Ptr; 

Ptr ; 

Longlnt ; 
Long In t; 
INTEGER; 
Longlnt ; 


{driver reference number} 

{not used} 

{read/write permission} 

{not used} 

{data buffer} 

{requested number of bytes} 
{actual number of bytes} 

{type of positioning operation} 
{size of positioning offset} 


IOPermssn requests permission to read from or write to a driver: 


IOPermssn 

0 

1 

2 

3 


I/O operation 

Whatever the driver is capable of doing 
Reading only 
Writing only 
Reading and writing 


This request is compared with the capabilities of the driver (some 
drivers are read-only, some are write-only). If the driver is 
Incapable of performing as requested, an error will be returned. 


IOBuffer points to an application's data buffer into which data is 
written by Read calls and from which data is read by Write calls. 
IOReqCount specifies the requested number of bytes to be read or 
written. IOActCount contains the number of bytes actually read or 
written. 


Advanced programmers: IOPosMode and ioPosOffset contain positioning 
information used for Read and Write calls by drivers of block devices. 
Bits 0 and 1 of IoPosMode indicate a byte position beyond the physical 
beginning of the block-formatted medium (such as a disk): 


IOPosMode 

0 

1 

2 

3 


Offset 

None 

Relative to beginning of device 
None 

Relative to current position 


IOPosOffset specifies the byte offset beyond ioPosMode where the 
operation is to be performed. 
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Routine Descriptions 

This section describes the procedures and functions* Each routine 
description Includes the low-level Pascal form of the call and the 
routine's assembly-language macro* A list of the fields in the 
parameter block affected by the call is also given* 


Assembly-language note : The field names given in these 
descriptions are those of the ParamBlockRec data type; see 
"Summary of the Device Manager” for the equivalent 
assembly-language equates. 


The number next to each parameter name indicates the byte offset of the 
parameter from the start of the parameter block pointed to by A0; only 
assembly-language programmers need be concerned with it. An arrow 
drawn next to each parameter name indicates whether it's an input, 
output, or input /output parameter: 

Arrow Meaning 

4 — Parameter is passed to the routine 

— > Parameter is returned by the routine 

4-> Parameter is passed to and returned by the routine 
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FUNCTION PBRead (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 




Trap macro 


Read 


Parameter block 


4-- 

12 

loCompletlon 

pointer 

— > 

16 

ioResult 

word 

4-- 

24 

IoRefNum 

word 

4— 

32 

loBuffer 

pointer 

4~ 

36 

loReqCount 

long word 

— > 

40 

io Act Count 

long word 

4~ 

44 

loPosMode 

word 

4-» 

46 

IoPosOffset 

long word 


Result codes noErr 

badUnitErr 

dSIOCoreErr 

notOpenErr 

unitEmptyErr 

readErr 


No error 

Bad reference number 

Device control entry was purged 

Driver Isn't open 

Bad reference number 

Driver Isn't enabled for read 

calls 


PBRead attempts to read loReqCount bytes from the driver having the 
reference number ioRefNum, and transfer them to the data buffer pointed 
to by loBuffer* After the read operation Is completed) the number of 
bytes actually read Is returned In loActCount. 


Advanced programmers: If the driver Is reading from a block device, 
the byte offset from the position indicated by loPosMode, where the 
read should actually begin, is given by ioPosOffset. 
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FUNCTION PBWrite (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 

JWrite 



Parameter block 





4~ 

12 

loCompletlon pointer 


— ^ 

16 

loResult 

word 


4— 

24 

loRefNum 

word 


4— 

32 

IoBuffer 

pointer 


4— 

36 

IoReqCount 

long word 


— » 

40 

IoActCount 

long word 


4— 

44 

IoPosMode 

word 


4~ 

46 

ioPosOffset 

long word 


Result codes 

noErr No error 

badUnitErr Bad reference number 

dSIOCoreErr Device control entry was 

purged 


notOpenErr Driver isn't open 

unitEmptyErr Bad reference number 

writErr Driver isn't enabled for 

write 



calls 



PBWrlte attempts to take ioReqCount bytes from the buffer pointed to by 
ioBuffer and write them to the driver having the reference number 
loRefNum* After the write operation is completed, the number of bytes 
actually written is returned in ioActCount. 

Advanced programmers: If the driver is writing to a block device, 
ioPosMode indicates whether the write should begin relative to the 
beginning of the device or the current position. The byte offset from 
the position Indicated by ioPosMode, where the read should actually 
begin, is given by ioPosOffset. 
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FUNCTION PBControl (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 




ioCompletion 

loResult 

ioRefNum 

csCode 

csParam 


pointer 

word 

word 

word 

record 


Trap macro _Control 

Parameter block 

< — 12 

— > 16 

4~ 24 

4~ 26 

4-- 28 

Result codes noErr 

badUnltErr 

dSIOCoreErr 

notOpenErr 

unitEmptyErr 

controlErr 


No error 

Bad reference number 

Device control entry was purged 

Driver isn't open 

Bad reference number 

Driver isn't enabled for control 

calls 


PBControl sends control information to the driver having the reference 
number refNum* The type of information sent is specified by csCode , 
and the information itself is pointed to by csParam* The values passed 
in csCode and pointed to by csParam depend on the driver being called* 


FUNCTION PBStatus (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 




Trap macro _Status 

Parameter block 

4 — 12 ioCompletion pointer 


— > 

16 

loResult 

4-- 

24 

IoRefNum 

4-- 

26 

csCode 

4— 

28 

csParam 


Result codes noErr 

badUnltErr 

dSIOCoreErr 

notOpenErr 

unitEmptyErr 

statusErr 


word 

word 

word 

variable 
No error 

Bad reference number 

Device control entry was purged 

Driver isn't open 

Bad reference number 

Driver isn't enabled for status 

calls 


PBStatus returns status information about the driver having the 
reference number refNum* The type of Information returned is specified 
by csCode, and the information Itself is pointed to by csParam* The 
values passed in csCode and pointed to by csParam depend on the driver 
being called* 
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FUNCTION PBKilllO (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Trap macro 


KilllO 


Parameter block 



12 

loCompletion 

pointer 

— > 

16 

ioResult 

word 

4— 

24 

ioRefNum 

word 


26 

csCode 

word 

<— 

28 

csParam 

variable 


Result codes noErr 

bad Unit Err 
dSIOCoreErr 
unltEmptyErr 
controlErr 


No error 

Bad reference number 

Device control entry was purged 

Bad reference number 

Driver isn't enabled for control 

calls 


FSK111I0 stops any current I/O request being processed, and removes all 
pending I/O requests from the I/O queue of the driver having the 
reference number reiNum. The completion routine of each pending I/O 
request is executed* 



THE STRUCTURE OF A DRIVER 


This section and the next describe the structure of drivers and how to 
write device drivers. If this information doesn't interest you, skip 
ahead to the summary. 

RAM drivers are stored in resource files. Drivers that will be used by 
more than one application should be stored in the system resource file, 
while those specific to an application should be stored in the 
application's resource file. 

The resource type for drivers is 'DRVR'. The resource ID for a driver 
is its unit number (explained below) and should be between 0 and 31 
inclusive. (The resource ID for a desk accessory must be greater than 
11.) Don't use numbers of existing drivers unless you want the 
existing driver to be replaced. The resource name should match the 
driver name. (The resource name for a desk accessory must contain a 
nonprinting character.) 

As illustrated in Figure 2, a driver begins with a few words of flags 
and other data, followed by offsets to the routines that do the work of 
the driver, an optional title, and finally the routines themselves. 
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byte 0 
2 
4 
6 
8 

10 

12 

14 

16 

18 


drvrFiogs vord 
drvrDe lay word 
tf'vrEMaskword 
drvrttenu word 
drvrOpen word 
drvrPrime word 
drvrCtl word 
drvrStatus word 
tf'vrClooe word 
drvrName word 


driver code 


flags 

number of ticks between SystemTask calls 

desk accessory event mask 

menu ID of menu associated with driver 

offset to opai routine 

offset to prime routine 

offset to control routine 

offset to status routine 

offset to close routine 

length byte and characters of driver name 


Figure 2. Driver Structure 


The drvrFlags word contains the following: 


Flat 

L 

Name 

bit 

8 

dReadEnable 

bit 

9 

dWritEnable 

bit 

10 

dCtlEnable 

bit 

11 

dStatEnable 

bit 

12 

dNeedGoodBye 

bit 

13 

dNeedTime 

bit 

14 

d Need Lock 


Meaning if set 

Driver enabled for Read calls 
Driver enabled for Write calls 
Driver enabled for Control calls 
Driver enabled for Status calls 
Driver needs to be called prior to 
application heap compactions 
Driver needs time for performing a 
periodic action 

Driver will be locked in memory as soon 
as it's opened (always set for ROM drivers) 


Bits 8 through 11 are the enable flags for the driver routines* Each 
flag that corresponds to a Device Manager call that the driver can 
respond to must be set* 


RAM drivers that exist on the application heap will be destroyed every 
time the heap is compacted (when an application starts up, for 
example)* If dNeedGoodBye is set, the control routine of the driver 
will be called before the heap is compacted, and the driver can perform 
any "clean-up" actions it needs to. The driver's control routine can 
identify this "good-bye" call by checking the csCode parameter — it will 
be -1. 
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If the dNeedTime flag is set, the drvrDelay word contains a tick count 
indicating how often the periodic action should occur. A tick count of 
0 means it should happen as often as possible, 1 means it should happen 
every 60th of a second, 2 means every 30th of a second, and so on. The 
action itself is performed by the control routine of the driver when 
it*s called by the Device Manager procedure SystemTask. The driver’s 
control routine can identify this periodic-action call by checking the 
csCode parameter— —it will be accRun. Normally only desk accessories 
will use dNeedTime and drvrDelay. 

DrvrEMask is used only for desk accessories and is discussed in the 
Desk Manager manual. If the driver has its own menu (or menus), 
drvrMenu contains the ID of the menu (or one of the menus); otherwise 
it contains 0. Normally only desk accessories have menus. 

Following these four words are the offsets to the driver routines, a 
title for the driver (preceded by its length in bytes), and the 
routines that do the work of the driver. 


A Device Control Entry 

The first time a driver is opened, information about it Is read into a 
structure in memory called a device control entry. A device control 
entry tells the Device Manager the location of the driver’s routines, 
the location of the driver's I/O queue, and other information. A 
device control entry is a 40-byte relocatable block located in the 
system communication area of the heap. It’s locked while the driver is 
open, and unlocked and purgeable while the driver is closed. 

The structure of a device control entry is illustrated in Figure 3. 
Notice that some of the data is taken from the first four words of the 
driver. Most of the data in the device control entry is stored and 
accessed only by the Device Manager, but in some cases the driver 
itself must store into it. 
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pointer to ROM driver or 
handle to RAM driver 
flags 

not used 

pointer to first entry in driver's I/O queue 
pointer to last entry in driver's I/O queue 
byte position used by Read end Write calls 
handle to driver's private storage 
driver's reference number 
counter for timing SystemTask calls 
pointer to driver's window record (if any) 
number of ticks between SystemTask calls 
desk accessory event mask 
menu 10 of menu associated with driver 


Figure 3. Device Control Entry 

The dCtlFlags word contains the following (bits 8 through 14 are copied 
from the drvrFlags word of the driver): 


byteO 

dCtl Driver long word 

4 

dCtl Flags word 

6 

dCtIQueue word 

8 

dCtIGHead pointer 

12 

dCtIQTail pointer 

16 

dCtl Position long word 

20 

dCt (Storage handle 

24 

dCtIRefNum word 

26 

dCtICurTicks long word 

30 

dCItWindow pointer 

34 

dCtl Delay word 

36 

dCtlEMaskword 

38 

dCtl Menu word 


Flat 

r 

L 

Name 

Meaning if set 

bit 

5 

dOpened 

Driver is open 

bit 

6 

dRAMBased 

Driver is RAM-based 

bit 

7 

drvrActive 

Driver is currently executing 

bit 

8 

dReadEnable 

Driver enabled for Read calls 

bit 

9 

dWritEnable 

Driver enabled for Write calls 

bit 

10 

dCtlEnable 

Driver enabled for Control calls 

bit 

11 

dStatEnable 

Driver enabled for Status calls 

bit 

12 

dNeedGoodBye 

Driver needs to be called prior to 
application heap compactions 

bit 

13 

dNeedTlme 

Driver needs time for performing a 
periodic action 

bit 

14 

dNeedLock 

Driver will be locked in memory as 
soon as it's opened (always set for 
ROM drivers) 


DCtlPosition is used only by drivers of block devices, and indicates 
the current source or destination position of a Read or Write call* 
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The position is given in number of bytes beyond the physical beginning 
of the medium used by the device* For example, if one logical block of 
data has just been read from a 3 1/2-inch disk via the Disk Driver, 
dCtlPosltion would be 512. 

ROM drivers generally use low-memory reserved locations for their local 
storage. RAM drivers may reserve space within their code space, or 
allocate a relocatable block and keep a handle to it in dCtlStorage 
(this memory is locked when the driver is opened, and unlocked when the 
driver is closed). 

DCtlCurTicks is used by the Device Manager to time SystemTask calls (if 
any were indicated by the dNeedTime flag in the driver). 


The Unit Table 


The location of each device control entry is maintained in a list 
called the unit table . The unit table is a 128-byte relocatable block 
containing 32 4-byte entries. Each entry has a number, from 0 to 31, 
called the unit number , and contains a handle to the device control 
entry for a driver. The unit number can be used as an index into the 
unit table to locate the handle to a specific driver's device control 
entry; it's equal to minus (the driver's reference number - 1). For 
example, the Sound Driver's reference number is -4, its resource ID is 
3. 

Figure 4 shows the layout of the unit table created at startup time 
with the standard Macintosh drivers. 
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byte 0 
4 
8 
12 
16 
20 
24 
28 
32 

48 

52 

56 

60 

64 

68 

72 

124 


not used 

not used 

Printer Driver 

Sound Driver 

Disk Driver 

Serial Driver port A input 

Serial Driver port A output 

Serial Driver port B input 

Serial Driver pert B output 

z not used Z 

Calculator 

Alarm Clock 

Key Caps 

Puzzle 

Note Pad 

Scrapbook 

Control Panel 

7 not used 7 

not used 


unit number 0 
1 

2 

3 

4 

5 

6 

7 

8 

12 

13 

14 

15 

16 

17 

18 

31 


Figure 4. The Unit Table 


Assembly-language note : The system global uTableBase points to 
the unit table* 


Each driver contains an I/O queue with a list of routines to be 
executed by the driver. There's one I/O queue for each device driver 
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(Figure 5). The queue's header is located in the device control entry 
for the driver. 



first queue last queue 

entry entry 


Figure 5. I/O Queue Structure 

DCtlHead points to the first entry In the queue, and dCtlTail points to 
the last entry in the queue. Each queue entry consists of a parameter 
block for the routine called — an abbreviation of which is given below: 

TYPE ParamBlockRec - RECORD 

ioLink: Ptr; {next entry} 

ioType: INTEGER; {always ioQType} 

ioTrap: INTEGER; {routine trap} 

ioCmdAddr: Ptr; {rest of block} 

• © • 

END; 

IOLink points to the next entry in the queue, and ioType indicates the 
queue type, which must be the value of the system global ioQType or 2. 
IOCmdAddr contains the address of the Device Manager routine called. 
IOTrap contains the trap (of the form $AXnn) of the routine called. 

The following system globals identify Device Manager traps: 


Name 

Value 

Trap 

Routine 

aRdCmd 

2 

$A002 

Read 

aWrCmd 

3 

$A003 

Write 

aCtlCmd 

4 

$A004 

Control 

aStsCmd 

5 

$A005 

Status 
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WRITING YOUR OWN DEVICE DRIVERS 

This section describes what you'll need to do to write your own device 
driver. The structure of the driver must match that shown In the 
previous section. The routines that do the work of the driver should 
be written to operate the device in whatever way you require. 

Your driver must contain routines to handle Open and Close calls, and 
may choose to handle Read, Write, Control, Status, and KilllO calls as 
well. The driver routines that the Device Manager will execute when 
one of these calls is made are as follows: 

Device Manager call Driver routine 


Open 


Open 

Read 

* 

Prime 

Write 


Prime 

Control 


Control 

KilllO 


Control 

Status 


Status 

Close 


Close 


When the Device Manager executes a driver routine to handle an 
application call, it passes a pointer to the call's parameter block in 
A0, a pointer to the driver's device control entry in Al, and 0 in D0. 
From this information, the driver can determine exactly what operations 
are required to fulfill the call's requests, and do them. 

Open and close routines must be executed synchronously. They needn't 
preserve any registers that they use. Open and Close routines should 
place a result code in D0 and return via an RTS. 

The open routine must allocate any private storage required by the 
driver, store a handle to it in the device control entry (in the 
dCtlStorage field), initialize any local variables, and then be ready 
to receive a Read, Write, Status, Control, or KilllO call. It might 
also install interrupt handlers, change interrupt vectors, and store a 
pointer to the device control entry somewhere in its local storage for 
its Interrupt handlers to use. The close routine must reverse the 
effects of the open routine, by deallocating all used memory, removing 
interrupt handlers, and replacing changed interrupt vectors. If 
anything about the operational state of the driver should be saved 
until the next time the driver is opened, it should be kept in the 
relocatable block of memory pointed to by dCtlStorage. 

Prime, control, and status routines are queueable (in other words, they 
can be executed asynchronously), and should be interrupt-driven. They 
can use registers A0 to A3 and D0 to D3, but must preserve any other 
registers used. Prime, control, and status routines should place a 
result code in D0 and return via an RTS, unless the device completes 
the I/O request Immediately, in which case they should JMP to the 
IODone routine (explained below). 
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(eye) 


Because they can be called as the result of an interrupt 
during a previous I/O request, these routines should 
never call Memory Manager routines that cause heap 
compactions* 


The prime routine must implement all Read and Write calls made to the 
driver* You may want to use the Fetch and Stash routines described 
below to read and write characters. If the driver is for a block 
device, it should update the dCtlPosition position after each read or 
write. The control routine must accept the control information passed 
to it, and manipulate the device as requested. The status routine must 
return requested status Information. As both the control and status 
routines may be subjected to Control and Status calls sending and 
requesting a variety of Information, they must be prepared to respond 
correctly to all types. 


Routines For Writing Drivers 


The Device Manager Includes three routines that provide low-level 
functions for drivers: Fetch, Stash, and IODone. Include them in the 
code of your device driver if they're useful to you. Fetch, Stash, and 
IODone are invoked via jump vectors rather than macros (in the interest 
of speed). These routines ' don ' t return a result code, as the only 
result possible is dSIOCoreErr, which invokes the System Error Handler. 
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FUNCTION Fetch (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 



j Fetch 

A0: pointer to device control entry 

D0: character fetched; bit 15-1 if it's the 
last character in the data buffer 


Parameter block 





12 

ioCompletlon 

pointer 

—> 

16 

ioResult 

word 


24 

loRefNum 

word 

<— 

32 

IoBuffer 

pointer 


36 

IoReqCount 

long word 


40 

ioActCount 

long word 


Fetch gets the next character from the data buffer pointed to by 
ioBuffer and places it in D0* IOActCount is Incremented by 1. If 
ioActCount equals ioReq Count, bit 15 of D0 is set* After receiving the 
last byte requested, the driver should call IODone. 


FUNCTION Stash (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 




vector 


j Stash 


A0: pointer to device control entry 
D0: character to stash 


On exit D0: bit 15-1 if it's the last character 

requested 

Parameter block 



12 

ioCompletlon 

pointer 

— » 

16 

IoResult 

word 

<— 

24 

loRefNum 

word 

<— 

32 

IoBuffer 

pointer 

«— 

36 

IoReqCount 

long word 

«— 

40 

ioActCount 

long word 


Stash places the character in D0 into the data buffer pointed to by 
ioBuffer, and increments ioActCount by 1. If ioActCount equals 
ioReqCount, bit 15 of D0 is set* After stashing the last byte 
requested, the driver should call IODone* 
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FUNCTION IODone (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Jump vector 
On entry 
On exit 


j IODone 

A0: pointer to device control entry 

D0: bit 15 a l if it's the last character 
in the buffer 


Parameter block 



12 

— » 

16 


24 

«— 

32 


36 

( — 

40 


ioCompletion 

loResult 

ioRefNum 

loBuf fer 

ioReqCount 

ioActCount 


pointer 
word 
word 
pointer 
long word 
long word 


Result codes 


noErr No error 

resErr Can't load driver from resource 

file 

unitEmptyErr Reference number specifies NIL 
handle In unit table 


IODone removes the current I/O request from the driver's I/O queue, and 
executes the completion routine (if there's one). It marks the driver 
inactive, and unlocks it and its device control entry (if it's allowed 
to by the dNeedLock bit of the dCtlFlags word). Then it begins 
executing the next I/O request in the I/O queue. 


Interrupts 

This section discusses Interrupts : how the Macintosh uses them, and 
how you can use them if you're writing your own device driver. Only 
programmers who want to write their own interrupt-driv^f device drivers 
need read this section. Programmers who want to build their own driver 
on top of a built-in Macintosh driver may be interested in some of the 
information presented here. 

An interrupt is a form of exception : an error or abnormal condition 
detected by the processor in the course of program execution. 
Specifically, an interrupt is an exception that is signaled to the 
processor by a device, as distinct from a trap, which arises directly 
from the execution of an instruction. Interrupts are used by devices 
to notify the processor of a change in condition of the device, such as 
the completion of an I/O request. An interrupt causes the processor to 
suspend normal execution, save the address of the next instruction and 
the processor's internal status on the stack, and execute an interrupt 
handler . 

The 68000 recognizes seven different levels of Interrupts, each with 
its own interrupt handler. The addresses of the various handlers, 
called interrupt vectors , are kept in a vector table in the system 
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communication area* Each level of Interrupt has Its own vector found 
at a definite fixed location In the vector table* When an Interrupt 
occurs, the processor fetches the proper vector from the table, uses It 
to locate the Interrupt handler for that level of interrupt, and jumps 
to the handler* On completion, the handler exits with an RTE 
instruction, which restores the Internal state of the processor from 
the stack and resumes normal execution from the point of suspension* 

There are three devices that can create Interrupts: the Synertek 6522 
Versatile Interface Adapter (VIA), the Zllog 8530 Serial Communications 
Controller, and the debugging switch* They send a 3-bit number, from 0 
to 7 , called the interrupt priority level . to the processor. The 
interrupt level indicates which device is interrupting, and indicates 
which interrupt handler should be executed: 

Level Interrupting device 

0 None 

1 VIA 

2 SCC 

3 Spurious 

4-7 Debugging button 

A level-3 interrupt occurs when both the VIA and SCC Interrupt at the 
same time; the interrupt handler for a level-3 Interrupt is simply an 
RTE instruction. Debugging interrupts shouldn't occur during the 
normal execution of an application. 

The interrupt priority level is compared with the processor priority in 
bits 8, 9, and 10 of the status register* If the Interrupt priority 
level is greater than the processor priority, the 68000 acknowledges 
the interrupt and initiates Interrupt processing* The processor 
priority determines which Interrupting devices are ignored, and which 
are serviced: 

Level Services 

0 All interrupts 

1 SCC and debugging interrupts only 

3-6 Debugging interrupts only 

7 No Interrupts 

When an interrupt is acknowledged, the processor priority is set to the 
Interrupt priority level, to prevent additional interrupts of equal or 
lower priority, until the interrupt handler has finished servicing the 
interrupt. 

The interrupt priority level is used as an index into the primary 
Interrupt vector table* This table contains 7 long words beginning at 
address $64. Each long word contains the starting address of an 
interrupt handler (Figure 6)* 




2/dd/84 Hacker 


CONFIDENTIAL 


/DEVICE. D 



30 


Device Manager Programmer's Guide 


$64 

autolntl 

pointer 

$68 

autolnt2 

pointer 

$6C 

' autolnt3 

pointer 

$70 

. autolnt4 

pointer 

$74 

autolnt5 

pointer 

$78 

autolnt6 

pointer 

$7C 

autolnt? 

pointer 


to level- 1 interrupt handler 
to level-2 interrupt handler 
to level-3 interrupt handler 
to level- 4 interrupt handler 
to level-5 interrupt handler 
to level-6 internet handler 
to level-? interrupt hcmdler 


Figure 6. Primary Interrupt Vector Table 


6. Execution jumps to the interrupt handler at the address specified 
in the table* 

The interrupt handler then must identify and service the Interrupt, and 
restore the processor priority, status register, and program counter to 
the values they contained before the Interrupt occurred. 


Level-1 ( VIA ) Interrupts 

Level-1 interrupts are generated by the VIA. You'll need to read the 
Synertek manual describing the VIA to use most of the information 
provided in this section. The level-1 interrupt handler determines the 
source of the Interrupt (via the VIA's IFR and IER registers) and then 
uses a table of secondary vectors in the system communication area to 
determine which interrupt handler to call (Figure 7). 
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byte 0 
4 
8 
12 
16 
20 
24 
28 


one-second interrupt 
vertical -retrace interrupt 
shift -register interrupt 
not used 


not used 

T2 timer: Disk Driver 
T1 timer: Sound Driver 
spur i ous (shouldn't occur) 


VIA CA2 control lira 
VIA CA1 control lira 
VIA shift register 


VIA timer 1 
VIA timer 2 


Figure 7. Level-1 Secondary Interrupt Vector Table 

The level-1 secondary interrupt vector table is pointed to by the 
system global lvllDT. Each vector in the table points to the Interrupt 
handler for a different source of Interrupt* The interrupts are 
handled in order of their entry in the table, and only one interrupt 
handler is called per level-1 interrupt (even if two or more sources 
are interrupting). This allows the level-1 interrupt handler to be 
reentrant, and interrupt handlers should lower the processor priority 
as soon as possible in order to enable other pending Interrupts to be 
processed. 

One-second Interrupts occur every second, and simply update the system 
global time. Vertical retrace interrupts are generated once every 
vertical retrace interval; control is passed to the Vertical Retrace 
Manager, which updates the system global ticks, handles changes in the 
state of the cursor, keyboard, and mouse button, and executes tasks 
installed in the vertical retrace queue. 

Whenever the Disk Driver or Sound Driver aren't being used, you can use 
the T1 and T2 timers for your own needs. 

If the cumulative elapsed time for all tasks on a level-1 Interrupt 
exceed 16msec (one video frame), a level-1 interrupt may itself be 
Interrupted by a vertical retrace interrupt. In this case, the 
vertical retrace Interrupt is cleared, and the vertical retrace tasks 
are Ignored. 

The base address of the VIA (the system global vBase) is passed to each 
interrupt handler in Al. 
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Level-2 (SCO Interrupts 

Level— 2 interrupts are generated by the SCC. You'll need to use the 
Zilog manual describing the VIA to effectively use the information 
provided in this section. The level-2 interrupt handler determines the 
source of the interrupt, and then uses a table of secondary vectors in 
the system communication area to determine which interrupt handler to 
call (Figure 8). 


byte 0 
4 
8 
12 
16 
20 
24 
28 


channel B transmit buffer empty 
channel B externa I/status change 
charnel B receive character available 
channel B special receive condition 
channel A transmit buffer empty 
channel A extemal/status change 
channel A receive character available 
channel A special receive condition 


mouse vertical 


mouse horizontal 




Figure 8. Level-2 Secondary Interrupt Vector Table 

The level-2 secondary interrupt vector table is pointed to by the 
system global lvl2DT. Each vector in the table points to the interrupt 
handler for a different source of interrupt. The interrupts are 
handled according to the following fixed priority: 

channel A receive character available and special receive 
channel A transmit buffer empty 
channel A external /status change 

channel B receive character available and special receive 
channel B transmit buffer empty 
channel B external/status change 

Only one interrupt handler is called per level— 2 interrupt (even if two 
or more sources are interrupting). This allows the level— 2 interrupt 
handler to be reentrant, and interrupt handlers should lower the 
processor priority as soon as possible in order to enable other pending 
interrupts to be processed. 

External/status interrupts pass through a tertiary vector table (Figure 
9) in the system communication area to determine which interrupt 
handler to call (Figure 9). 
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byte 0 
4 
8 
12 


channel B nonmouse interrupt 
mouse vertical interrupt 
channel A nonmouse interrupt 
mouse horizontal interrupt 


Figure 9. Level-2 External/Status Interrupt Vector Table 


The external/status Interrupt vector table Is pointed to by the system 
global extStsDT. Each vector In the table points to the interrupt 
handler for a different source of interrupt* Nonmouse Interrupts 
(break/abort, for example) always handled before mouse interrupts* 


When a level-2 interrupt handler is called , D0 points to the SCC read 
register 0 (external/status Interrupts only), and D1 points to the SCC 
read register 0 containing the changed bits since the last 
external/status interrupt. A0 points to the SCC channel A or channel B 
control read address and A1 points to SCC channel A or channel B 
control write address, depending on which channel is Interrupting* The 
SCC's data read address and data write address are located 4 bytes 
beyond A0 and Al, respectively* The following system global? can be 
used to refer to these locations: 


System global Value 
sccRBase $9FFFF8 

sccWBase $BFFFF9 

bCtl 0 

aCtl 2 

bData 4 

aData 6 


Refers to 
Base read address 
Base write address 
Offset for channel B 
Offset for channel A 
Offset for channel B 
Offset for channel A 


control 

control 

data 

data 


Writing Your Own Interrupt Handlers 

You can write your own interrupt handlers to replace any of the 
standard Interrupt handlers just described* Be sure to place an 
interrupt vector that points to your Interrupt handler in one of the 
interrupt vector tables. 

Both the level-1 and level-2 interrupt handlers preserve A0 through A3 
and D0 through D3. Every interrupt handler (except for external/status 
interrupt handlers) is responsible for clearing the source of the 
interrupt, and for saving and restoring any additional registers used. 
Interrupt handlers should return directly via an RTS, or, if the I/O 
requested by the handler is completed Immediately, via a JMP to IODone. 
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Any software action indicating that interrupts are being 
enabled should be taken before the corresponding hardware 
action, lest an interrupt occur before the software has 
been told such an event is possible. 

Any software action indicating that interrupts are being 
disabled should be taken after the corresponding hardware 
action, lest one interrupt slip in with the software 
thinking that Interrupts are off. 


A Sample Driver 


Here's the skeleton of the Disk Driver, as an example of how a driver 
should be constructed. 


SonyDrvr 

• 

• 

e 


;read, write, control. •• 

.WORD 

$4F00 


.WORD 

0,0 

?no delay or event mask 


.WORD 

0 

;no menu 

; Entry-point 

offset table 



.WORD 

DiskOpen-DiskDrvr 

;open 


.W0RD 

DiskPrime-DiskDrvr 

; prime 


.WORD 

DiskControl -Di skDrvr 

; control 


.WORD 

DiskStatus-DiskDrvr 

; status 


.WORD 

• 

e 

DiskRTS-Di skDrvr 

;close (just RTS) 

;Disk Driver 

e 

routines 



DiskOpen 

MOVEQ 

/KDiskVarLth/ 2 > , D0 


DiskRTS 

• » • 

RTS 



Disk Done 

• • • 

JMP 

IODone 


DiskControl 

• • • 

MOVE.L 

JControl ,-(SP) 


DlskStatus 

• • t 

MOVEQL 

#StatusErr,D0 


DiskPrime 

• • • 

MOVE.L 

JDiskPrime , ( -SP ) 
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SUMMARY OF THE DEVICE MANAGER 


Constants 


CONST goodByeCode * -1 ; 


Data Structures 


TYPE ParmBlkPtr « ~ParamBlockRec ; 

ParamBlkType = (ioParam, file Par am, volumeParam, controlParam); 
ParamBlockRec = RECORD 


ioLink: 

Ptr; 

ioType: 

INTEGER; 

ioTrap: 

INTEGER; 

ioCmdAddr: 

Ptr; 

ioCompletion: 

ProcPtr; 

ioResult: 

INTEGER;, 

ioNamePtr : 

OSStrPtr 

ioVRefNum: 

INTEGER; 


CASE ParamBlkType OF 
ioParam: 
fileParam: 
volumeParam: 
controlParam: 

END; 

TYPE OpVariant = (sound, asyncRst, asyncInBuff, asyncShk, printer, 

fontMgr, diskDrv, asyncBuff Bytes, asyncStatus, 
diskStat) ; 
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TYPE OpParamPtr » '‘OpParamType ; 

OpParamType “ RECORD 

CASE OpVariant OF 

{control Information} 
sound: 

(sndVal: INTEGER); 
asyncRst : 

( asncConf ig : INTEGER) ; 
asyncInBuf f : 

(asncBPtr: Ptr; 
asncBLen : INTEGER) ; 
asyncShk: 

(asncHndShk: Longlnt; 
asncMisc : Longlnt ) ; 
printer: 

(paraml: Longlnt; 
param2: Longlnt; 
param3 : Longlnt ) ; 
fontMgr : 

(fontRecPtr: Ptr; 
fontCurDev: INTEGER); 
diskDrv: 

(diskBuff: Ptr); 

{status information} 
asyncBuff Bytes : 

(asyncNBytes: Longlnt); 
asyncStatus : 

(asncSl: INTEGER; 
asncS2: INTEGER; 
asncS3: INTEGER); 
diskStat: {Disk Driver} 

(dskTrackLock: INTEGER; 
dsklnfoBits: Longlnt; 
dskQElem: drvrQElRec; 

dskPrime: INTEGER; 

dskErrCnt : INTEGER) ; 

END; 


{Sound Driver} 
{Async Driver} 

{Printer Driver} 

{Font Manager} 
{Disk Driver} 
{Async Driver} 


Routines For Opening and Closing Drivers 

FUNCTION OpenDriver (fileName: OSStr255; VAR refNum: INTEGER) : OSErr; 
FUNCTION CloseDriver (refNum: INTEGER) : OSErr; 
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High-Level Routines 

FUNCTION FSRead (refNum: INTEGER; VAR count: Longlnt; buffPtr: Ptr) 

: OSErr; 

FUNCTION FSWrite (refNum: INTEGER; VAR count: Longlnt; buffPtr: Ptr) 

: OSErr; 

FUNCTION FSControl (refNum: INTEGER; opCode: INTEGER; opParams: 

OpParamPtr) : OSErr; 

FUNCTION FSStatus (refNum: INTEGER; opCode: INTEGER; VAR opParams: 

OpParamPtr) : OSErr; 

FUNCTION FSKilllO (refNum: INTEGER) : OSErr; 


Low-Level Routines 


FUNCTION 

PBRead 

(paramBlock: 

ParmBlkPtr; 

async : 

BOOLEAN) 

OSErr ; 

FUNCTION 

PBWrite 

(paramBlock: 

ParmBlkPtr; 

async : 

BOOLEAN) 

OSErr; 

FUNCTION PBControl (paramBlock: 

ParmBlkPtr; 

async : 

BOOLEAN) 

OSErr ; 

FUNCTION 

PBStatus 

(paramBlock: 

ParmBlkPtr; 

async : 

BOOLEAN) 

OSErr; 

FUNCTION 

PBKilllO 

( paramBlock : 

ParmBlkPtr; 

async : 

BOOLEAN) 

OSErr ; 

Routines 

For Writing Drivers 



- 



FUNCTION Fetch (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
FUNCTION Stash (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 
FUNCTION IODone (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr; 


Assembly-Language Information 


Constants 


ioQType 

.EQU 

2 

aRdCmd 

.EQU 

2 

aWrCmd 

.EQU 

3 

aCtlCmd 

.EQU 

4 

aStsCmd 

.EQU 

5 

sccRBase 

.EQU 

$9FFFF8 

sccWBase 

.EQU 

$BFFFF9 

bCtl 

.EQU 

0 

aCtl 

.EQU 

2 

bData 

.EQU 

4 

aData 

.EQU 

6 


;I/0 request queue entry type 
;ioTrap type for Read call 
;ioTrap type for Write call 
;ioTrap type for Control call 
;ioTrap type for Status call 
;SCC base read address 


;SCC base write 

address 



;Offset 

for 

see 

channel 

B 

control 

;Off set 

for 

see 

channel 

A 

control 

; Offset 

for 

see 

channel 

B 

data 

;Offset 

for 

see 

channel 

A 

data 
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Standard Parameter Block Data Structure 




ioLink 

ioType 

ioTrap 

ioCmdAddr 

ioCompletion 

ioResult 

ioFileName 

ioVNPtr 

ioVRefNum 

ioDrvNum 


Next queue entry 
Always fsQType 
Routine trap 
Routine address 
Completion routine 
Result code 

File name (and possibly volume name too) 
Volume name 

Volume reference number 
Drive number 


Control and Status Parameter Block Data Structure 

csCode Type of Control or Status call 

csParam Parameters for Control or Status call 


I/O Parameter Block Data Structure 


ioRefNum 
ioFileType 
ioPermssn 
ioBuf fer 
ioReqCount 
ioActCount 
ioPosMode 
ioPosOf fset 


Driver reference number 
Not used 
Open permission 
Data buffer 

Requested number of bytes 
Actual number of bytes 
Type of positioning operation 
Size of positioning offset 


Macro Names 


Routine name 

PBRead 

PBWrite 

PBControl 

PBStatus 

PBKilllO 


Macro name 
_Read 
_Write 
_Control 
_Status 
KilllO 




System Globals 

Name Size 

uTableBase 4 bytes 

unitNtryCnt 2 bytes 


Contents 

Pointer to the unit table 

Maximum number of entries in the unit 

table 
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Result Codes 


Name 

abortErr 

badUnitErr 

controlErr 

dlnstErr 

dRemoveErr 

dSIOCoreErr 

memFullErr 

noErr 

notOpenErr 

openErr 

readErr 

resErr 

statusErr 

unitEmptyErr 

writErr 


Value Meaning 

-27 10 call aborted by KilllO 

-21 Reference number doesn't match 

unit table 

-17 Driver isn't enabled for control 

calls 

-26 

Couldn't find driver in resource file 
-25 Tried to remove an open driver 
14 Device control entry was purged 

-108 Memory full 

0 No error 

-28 Driver isn't open 

-23 Requested read/write permission 

doesn't match driver's open permission 
-19 Driver isn't enabled for read calls 
Resource Manager error 
-18 Driver isn't enabled for status calls 
-22 Reference number specifies NIL 

handle in unit table 

-20 Driver isn't enabled for write calls 
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GLOSSARY 

asynchronous execution: During asynchronous execution of a routine, 
the Device Manager is free to perform other tasks* 

block device: A device that reads and writes blocks of 512 characters 
at a time; it can read or write any accessible block on demand* 

character device: A device that reads or writes a stream of 
characters, one at a time: it can neither skip characters nor go back 
to a previous character* 

closed driver: A driver that cannot be read from or written to* 

close routine: The part of a driver* s code that implements Device 
Manager Close calls* 

completion routine: Any application-defined code to be executed when 
an asynchronous call to a Device Manager routine is completed* 

control information: Information transmitted by an application to a 
driver; it can typically select modes of operation, start or stop 
processes, enable buffers, choose protocols, and so on* 

control routine: The part of a driver’s code that implements Device 
Manager Control and Kill 10 calls* 

data buffer: Heap space containing information to be written to a 
driver from an application, or read from a driver to an application* 

device: A part of the Macintosh or a piece of external equipment, that 
can transfer information into or out of the Macintosh* 

device control entry: a 40-byte relocatable block of heap space that 
tells the Device Manager the location of a driver's routines, the 
location of a driver's I/O queue, and other information* 

device driver: a program that exchanges information between an 
application and a device* 

driver name: A sequence of up to 255 printing characters; driver names 
are always prefixed by a period (.)• 

driver reference number: A number that uniquely identifies an 
individual driver* 

exception: An error or abnormal condition detected by the processor in 
the course of program execution* 

interrupt: An exception that is signaled to the processor by a device, 
to notify the processor of a change in condition of the device, such as 
the completion of an I/O 
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interrupt handler: A routine that services interrupts. 

interrupt priority level: A number identifying the importance of the 
interrupt. It- indicates which device is interrupting, and which 
interrupt handler should be executed. 

interrupt vector: A pointer to an interrupt handler. 

I/O queue: A queue containing the parameter blocks of all I/O requests 
for one driver. 

I/O request: A request for input from or output to a driver; caused by 
calling a Device Manager routine asynchronously. 

open driver: A driver that can be read from and written to. 

open routine: The part of a driver's code that implements Device 
Manager Open calls. 

parameter block: An area of heap space used to transfer information 
between applications and the Device Manager. 

prime routine: The part of a driver's code that implements Device 
Manager Read and Write calls. 

processor priority: Bits 8, 9, and 10 of the status register, that 
indicate which interrupts will be processed and which will be ignored. 

status information: Information transmitted to an application by a 
driver; it may indicate the current mode of operation, the readiness of 
the device, the occurrence of errors, and so on. 

status routine: The part of a driver's code that implements Device 
Manager Status calls. 

synchronous execution: During synchronous execution of a routine, the 
Device Manager must devote all of its attention to the routine, and 
isn't free to perform any other task. 

unit number: The number of each driver's entry in the unit table. 

unit table: A 128-byte relocatable block containing a handle to the 
device control entry for each device driver. 

vector table: A table of vectors in the system communication area. 
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SAD MACINTOSH ICON 
OCT 26, 1983 
?aM Keiu^cA 


Here is a example: 

Power oa Che Macintosh, holding down Che NMI button on the left side of Che 
. computer. The sad Macintosh will appear, with a set of numbers under it. 

This set of code can be divided into two types of code. 

OF f 00D - Sub Codes 

I 

Class Codes 

Class Codes deals with the initial diagnostic code. 

1 ” ROM test failed meaningless 

2 * Memtest - Bus subtest bits set corresponds to suspected bad RAM chips 

3 * Memtest - ByteWrite * 

4 » Memtest - Mod3test " * 

5 “ Memtest - Addr uniqueness " ' . * 

• i. . ; -v*‘ •. ; 

Class Code F m exception, only after diagnostics have passed. 

This is where the Sub Codes come in. : 

F - exception 0001 Bus error 

0002 address error 

0003 illegal instruction 

0004 zero divide 

0005 check instruction 

0006 trapv instruction 

0007 privilege violation 

0008 trace 

_ 0009 line 1010 

^ 000A line 1111 

000B other exceptions 
000C nothing 
000D NMI 


Another test to see how this works is, remove a RAM chip. Power up the Macintosh. 




A new code should appear under the sad Macintosh icon. When I did it, I picked 
the one closes to the Keyboard connector. The code under the Macintosh was 
028000. So number 2's class code tells me that it suspects bad RAM chip. The 
eight tells me that its the 15th RAM chip. 

RAM Chip # Code under Macintosh ‘ 


0 

1 

2 

3 

4 

5 


0001 

0002 

0004 

0008 

0010 

0020 


6 

m 

0040 

7 

m 

0080 

8 

m 

0100 

9 

m 

0200 

10 

m 

0400 

11 

m 

0800 

12 

m 

1000 

13 

m 

2000 

14 

m 

4000 

15 

m 

8000 


This is s good example of just one RAM chip being bad , but what is there are 
multiple RAM chips that are bad? Try taking the 15th and 14th RAM chips out. 
the Code appears like this. 02C000, we can say since we know the code is in Hex 
that there are 16 possibilities. 


0 0000 * V>. * 

1 0001 
2 0010 
3 0011 

4 0100 

5 0101 

6 0110 . ; -,v * ; 

7 0111 

8 1000 ; 

9 1001 

A 1010 
B 1011 

C 1100 meaning tne 15th and 14th chip is bad. 
D 1101 
E 1110 
F 1111 




This is just a start to understanding what all the codes mean. If we try to keep 
a list, we should come across all the possibilities. 



October 22, 1983 


To: 

From: 

Re: 


Distribution 
Chris Espinosa 

More Outstanding Issues in User Education Materials 


^hi s list has been updated to include Lisa/Mac compatibility issues, and 
to summarize resolved issues. 
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Macintosh User Education 


ISSUES RESOLVED 

These are agreements ve have reached on previous outstanding issues* 

INITIALIZING DISKS: Upon an Eject, the formatting package will be 
loaded in and not released until the next subsequent remount. Upon a 
remount with a disk I/O error, the application will call the package to 
give the user the option to either initialize or eject the disk. 

On -the— fly initializing won’t put boot blocks on the disk. Booting a 
data disk results in the small "bad disk" icon, and ejects the disk. I 
recommend that when the user moves System or Finder to a different 
disk, chat System, Finder and bootblocks all be copied. 

WORKING VOLUME. This will be virtually transparent to the user. 

OFF-LINE VOLUMES. The Anonymous disk v will appear in the Finder. It 
still needs a name. 

WRITE-PROTECTED DISKS. The Finder will work on a write-protected disk. 
MacWrite. and MacPaint will work if the document's volume is not 
write-protected, even if the application'.!; volume is. 

WRITE-PROTECTED FILES. Save' will* nor '-Overwrite a write-protected filet 
the user will have to save somewhere else, quit, remove 
write-protection, remove the file, arid rename the new one. The 
mechanism for setting/clearing write-protection is assumed to be the 
Finder's "Get Info" box. It should lock the file's position in the 
Finder. Get Document gives no warning chat the file is 
write— protected . Write-protection does it lock the file's position in 
the Finder, so you can't drag it. If you move or duplicate it, it does 
retain its protection. 

ONE-DRIVE COPY. The mechanism is as described in the Finder specs. It 
will be implemented October 25 or later. 

FILE MENU— Most issues have been resolved. We hope the on-the-fly 
formatter will cure the full-memory— full-disk problem; in any case, 
we'll still recommend chat users format all blank disks at once. Save 
and Overwrite actually rewrites the existing file; there will be no 
option to "write new, delete old", as the Pascal Editor does. 

PRINTING IN THE FINDER. Applications will respond to the Filer's 
'Print' message. The Finder itself knows how to print a directory; the 
user interface is still unresolved. 

PRINTING AND PAPER. A paper-loading position has been standardized: 
cop edge of paper parallel with the cop of the paper bail rollers; 
edges of the paper centered around Che two red alignment marks on the 
paper bail. 
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EXTERNAL DISK. Document its connection' and use. 

MODEM. Document its connection. 

CLIPBOARD. MacWrite will write text and individual pictures, and read 
text and individual pictures. MacPaint will write pictures and read 
text and pictures. Calculator and; ddcte, will read and write text. 
Gallery will read and write text and pictures. 

RECOVERY OF REMOVED DOCUMENTS. Trashed files are lost without warning 
when starting a new application or ejecting the disk. 

DESK ACCESSORIES. Here's the basic set: 

Clock — Time and date in local format, mouse-editable. Cut, paste, 
copy. Unresolved: Alarm 

Calculator — four-function algebraic. Cut, paste, copy. 

Unresolved: exponents; does the Enter key do equals, then copy? 

Note Pad — At least one "sheet" of text, no scrolling, Cut, Paste, 
Copy. 

Gallery— Multiple sheets of pictures or text, scrolling through. 
Cut, Paste, Copy. 

Control Panel— Speaker volume, Keyboard click, keyboard repeat 
speed and delay, mouse scaling, paranoia level, desk pattern edit, 
clock setting, double click spee&. 

Calendar — first time I've heard of. it! Is it separate from the 
Clock? 

Puzzle— same in appearance to current one. 

CLOCK. The clock's time will not be set; the user must set it to local 
time. The mechanism for setting it is via the clock desk accessory or 
the control panel. The Finder dialog box will cease to be. 
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MACWRITE— INSERTING PAGE BREAKS, VISIBLE PAGE BREAKS. These features 
are in. 

ICON SELECTION. Closing a window in the finder leaves that window's 
icon selected. 

MACWRITE— MODELESS FIND DIALOG. We're documenting it now. 

FINDER WINDOWS. Information windows will be staggered in an 
interesting fashion, so you can pick any one out. 

FINDER CLIPBOARD. Opening the Clipboard window shows the current 
clipboard; there is only one clipboard. If in the Finder you attempt 
to Cut or Copy and the clipboard currently contains something large, an 
alert box warns you you're about to. clobber it. 

* y '< * 

ARRANGEMENT MENU. Alphabetical and chronological will be functional at 
launch. 

FONTS. System, a sans-serif font, a serif font, a monospace font, a 
small font, and a pretty font. Names TBl3.. 

• i. . ; ~v*‘ *, 

OPEN A GROUP SELECTION. If you select both an application and a 
compatible document (even if that’s not the document's primary 
application), and choose Open, it will.'run chat application with that 
document. 

TWO-DRIVE SYSTEMS. The Finder looks around for an application on othec 
drives. 

PARAMETER RAM. Some applications use it. We will have a control 
panel • 
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SERIOUS ISSUES 


These topics are highly visible to the user and must be covered 
truthfully in the manuals. The decisions can affect the flow of the 
tutorial or the amount of coverage in the reference section. Changes 
to these will affect the page count of the manual and set back the 
schedule . 

INITIALIZING DISKS. Still unresolved: whether on-the-fly is possible 
at all, will the package always be RAM-resident, how new disks are 
named. 

SYSTEM VS. DATA DISKS. How will boot blocks be placed? (I recommend 
that whenever a user attempts to move System or Finder to a data disk, 
that all the System, Finder, and bootblocks go too.) 

t * ; • . 

WRITE— PROTECTED FILES. Solidify the Finder mechanism for protecting 
and unprotecting documents. 

STATIONERY. The stationery protocol is different in the Finder than in 
the Get dialog. These must be resolved.-' 

• ; - v*' *. ■; - 

RESOURCE REPRESENTATIVES. Will they make it into the announced 
product? , . 

CLIPBOARDS" What will Plan cut and paste? 

MACWRITE-— PRINTING. Under what circumstances can/will you run a second 
application? 

MACWRITE— — PRINTING. What are PRAPP and Print? What's the difference? 

MACWRITE— -TEXTFILES . Are these loaded through the Scrap or by using 
check-boxes in the Get and Save dialogs? 

MACWRITE—PRINTING. Will Mac Write print wide? 

FOLDERS. When you drag a folder from one disk to another, does it 
duplicate that folder and all files in that folder on the new disk? Do 
the duplicate files end up inside the duplicate folder? 

FINDER-— SELECT ALL. Is this item worthwhile, if it only selects the 
entirety of some current text? 

BOOTSCREEN. Will there be one? How do people make their own? Will we 
ship ConvertDoc? 
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TERMINOLOGY 

These terminology issues percolate throughout the manuals , both in text 
and in screen shots. Changes to these will not affect pagination, but 
will force the re-typesetting of many pages. 

FINDER. Choices for its name are Finder, Desktop Manager, Organizer. 
Beta drafts use the latter. 

WP. Preferably its name on the disk will be MacWrite. 

SYSTF A DISK. This should be its volume name. 

CLIPBOARD. As per 9/31 user interface powwow. 

TRASH. Or Wastebasket, Trash Can* Garbage . Manuals use Trash Can; 

Lisa uses Wastebasket. Current choice: Trash. 

ANONYMOUS DISK. Needs a name. 

TYPE. "File type" as a concept or keyword. Do we introduce the 
four-letter mnemonics? 

• . ; -v* '• ; 

GET INFO. Alternate term, as it both gets and sets information. 

DIRECTORY. Considering using this as the name for the "document 
consisting of the names and icons on a disk or in a folder". Somehow 
"catalog" has more of a pictorial implication, which is not^ valid in 
the Open dialog. We're also thinking of just calling it a ’list and 
leaving it at that. 

HIRES/LORES. Better terms for print quality /speed. Current candidates 
are "Quality: High, Normal, Draft" 

ROTN. "Print orientation" is unwieldy but accurate. Adjectives are 
"Tall" and "Wide". 


THE WORDS 


The dialog boxes, menus, button labels, window titles, and icon names 
must all match the terminology used in the manuals, and must be in 
clear, concise English. Dialog boxes should present a consistent 
appearance, with familiar locations fbr common buttons and fields. 

We have the resource definition files for System, MacWrite, the Finder 
and the Bootblocks. We do not have MacPaint; we expect the Finder to 
change. We have marked up the ones we have with our suggestions. I 
would still enjoy it if Susan and/or Ellen could then use the Dialog 
Box editor to clean up the appearance of some of the dialog boxes. 
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OTHER ISSUES THAT DON'T AFFECT MANUALS 


Here are some ocher chings I worry about: 

RESOURCE FOLLOWING* Is Randy recording the names of the fonts used in 
a document in that document's resource file? If not, what happens if 
one of those fonts goes away? 

OPEN A GROUP SELECTION. If you select both an application and a 
compatible document (even if that's not the document's primary 
application), and choose Open, will it run that application with that 
document? It doesn't do it now* 


TWO-DRIVE SYSTEMS, 
other drives? 


Does the Finder look around for an application on 

■ * v; - • ; • 


RESET AND REBOOT. It puzzles me that rebooting, via the boot button or 
a Deep Shit alert, often doesn't successfully reboot the machine, while 
power-off/power/on does. Obviously somebody in the boot process is 
reading some state that's cleared on power-down/power— up but not on a 
manual reboot. It just shouldn't happen'^ • 

• i. . ; - vi' *, ; - 

PARAMETER RAM. Does anybody use it? Will we have a control panel? 


RESOURCE FOLLOWERS. Do third-party applications define their own 
icons? Do we? 


DOUBLE-CLICK. Are most people using the same algorithm? The one I've 
heard: On an upstroke, if the last downstroke followed the last 
upstroke by 700 milliseconds or less, and the pointer has moved fewer 
than epsilon pixels horizontally and vertically from the last 
downstroke, it's a double-click. Epsilon starts at about 5. 

TEXT SCRAP FORMATS. There's no suggestions for how to handle Tabs, 
Return characters, etc. in the text scrap. If we're going to transfer 
digits from Plan to Write, we'll have to have some construct like this. 



ROM 7 .0 MacsBug Summary 


To use MacsBug, include it on your Mac diskette* The system will say 'MacsBug 
installed' when the diskette is booted. You may also include the Disassembler 
in the same manner. 


The Mac's modem port should be connected to another computer or terminal 
running at 9600 baud, no parity. Press the interrupt switch after booting the 
disk. The mouse should freeze and no error message should appear. On the 
terminal, a register dump should appear, and an asterisk '*' prompt. 


Commands available : 


DM 

SM 

D# 

A# 

SR 

n 

jS 

ss 

BR 


A 

D 

TD 

CV 


T 

AT 


Display Memory 
Set Memory 


DM 100 100 

SM 0 1 2 3 4 5 6 


DM RA7 ,-10 20 
SM 0 'ABODE' 


Display/Set data register # 
Display/Set address register # 
Display/Set status register 
Display/Set program counter 
Display /Set user stack 
Display/Set supervisor stack 


DO 0000FFFF 
A0 


(normally A7) 
(normally A7) 


Display/Set break points 

(up to eight) 


BR 

BR 4DD0 552A 
BR CLEAR 


Display all address registers 
Display all data registers 
Display all registers 


Convert between base 10 and 16 
(all arithmetic is 32 bit) 


CV $FDEF 
CV 665536 


To do hexidecimal addition, use CV $numl,num2 
To do hexidecimal subtraction, use CV $numl ,-num2 
To do hexidecimal negation, use CV $-numl 


Go 

(continue) 

G 



(start at 44D0) 

G 4 4 DO 



(continue until PC * 55EA) 

G TILL 

55EA 

Trace 


T 17 


Trace Traps 

(traces all traps) 

AT 



(trace GetNextEvent) 

AT 170 



(trace all Bit Traps) 

(trace GetNextEvent in code 

AT 158 

15F 


block at 5000 - 53FF) 

(trace all Bit Traps in code 

AT 170 

5000 53FF 


block at 5000 - 53FF) 

AT 158 

15F 5000 53FF 



AB Break Traps same as AT, but breaks before executing trap 

HD Handle Display lists all allocated handles HD 

AD Data Break AD 158 15F 5000 53FF 

A simple checksum is calculated for the specified memory range. 

As each Trap is encountered, the checksum is recalculated. 

If the checksum differs, the debugger breaks. This call must 
be made with all four arguments. 

AX Cancel Break AX 

Clears the current AT, AB, AH, AC, or HS command 


Disassembler Calls 


IL 

List 


IL 4DD0 


lists the 

next 20 instructions' ‘ * 

IL 

ID 

List One 


ID 4DD0 


lists one 

instruction 

ID 



De bugge r . Na4?a Ci on 

- 

/ 

Command Separator 

SM PC 4E71 / G 

• 

Last Address • 



(for DM, SM, IL, ID) 

DM . 100 

f 

Offset 

DM .,100 100 

RA# 

Address Register 

DM RA7.-10 20 

RD# 

Data Register 

SM RAO, RD2 


Advanced Debugger Calls 


AH 

Heap Break 

AH 158 15F 


A heap check is made as each specified Trap is encountered. 
If $1A3E8 * 0 then the applzone is checked. (default) 

If $1A3E8 <> 0 then SysZone is checked. The trap range must 
be greater than $2E. 

An error returns: Bad Heap at A1 A2 where: 

A1 - the previous block pointer 
A2 ■ the bad block pointer 









HC Heap Check HC 

ihis call checks the heap as described in AH. An error is 

returned if any of the following conditions are true: 

The block size is past the top of memory 
The block size is odd 

For tree blocks, the next link is negative or past the top of memory 

For tree blocks, the previous link is negative or past the top of memory 

For rel. blocks, the back pointer is odd 

The heap base + back pointer is past the top of memory 

The heap base + back pointer do not point to the right master pointer. 

HS He ip Scramble HS 

If the traps NewPtr, SetPtrSize, NewHandle, SetHandleSize , HandleZone or 
ReAllocHandle are encountered, the heap is scrambled before executing 
the trap. It also preforms a he^p. check before scrambling on all traps 
> 30. 

MR Magic Return MR 

This assumes the first word on the stack is a return address generated 
by a BSR or JSR. It substitutes a ( break point for the return address. 
The execution continues until' a - btiak*' occurs. Then, SR is restored. 

This is not nestable. All other break point commands are still active. 


Known Problems 

It is a good idea to initialize DM and IL. DM 0, and ID PC, for 
example. 

DM RAS, as example, intermittently generates an address error. 

To fix, explicitly type the address in register. 

SM PC 4E71, for example, makes the system respond unreliably if 
a trap or breakpoint was set at that location* 

AT, as example, returns a Line 1111 exception. To fix, reboot. 



Pascal Program Debug Strategy 


Use DM to determine where the program is in memory* Seven letters of each 
procedure and function will appear in the ASCII columns* (The first letter 
has its high bit set.) The user program usually starts about 4DD0. The 
mainline procedures and functions are first, followed by the units and 
external procedures and functions in the order that you link them* Each 
procedure or function name suceeds the procedure or function code* To make 
life easier, link your own units before linking ToolTraps, MemTraps and 
MacPasLib* 

If the program doesn't appear to work at all, find the address of the start 
of the program. It will be immediately after the name of the last procedure 
or function. 

If you disassemble at that address, you will see a LINK instruction for A6 and 
a LINK instruction for A5. These address registers are used by Pascal to 
locate all variables and procedural parameters.; Global variables are 
referenced negatively off A5* Local variables are referenced negatively off 
A6* Procedural parameters are referenced with a positive offset from A6. 

ToolBox calls and other calls to unit-resident procedures and functions are 
made through JSR *+addr instructions. The table ToolTraps is linked to your 
program, and contains all of the actual calls 'themselves. 

• . ; -v** ♦. ; " 

If you are writing a Pascal program that uses the ToolBox, the first- thing 
you probably do is: : 

InitGraf (dthePort); 

This assembles into: 

LEA $FF1E(A5),A0 

MOVE.L AO ,A7 
JSR *+addr 

You should see this shortly after the LINK instructions. This establishes 
the beginning of your program. 

To find out where this program fails, interrupt the Finder. Set G TILL addr 
where addr is the beginning of your program. Restart your program. If the 
program breaks sucessfully at that point, continue to use G TILL to selectly 
execute your program until it fails more spectacularly, or locks up. 

You will find that the 68000 code that the Pascal compiler produces is 
reasonably readable, and that the compiler produces smart code. 



To complement the debugger Information , you may want to add debugging code 
in your program itself. One easy way to do so is to do WRITE s or WRITELN 
:o the .BOUT port. This information will appear on your debugging terminal 
The code fragments required look like: 


VAR debug : TEXT; 

REWRITE (debug, '.BOUT’); 

WRITELN (debug, chr(10) {linefeed}, 'This is a test', 12345); 

WRITE and WRITELN support strings, chars, packed array of chars, integers, 
and booleans. 
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See Also: The Resource Manager: A Programmer's Guide 
QuickDraw: A Programmer's Guide 
The Font Manager: A Programmer's Guide 
The Dialog Manager: A Programmer's Guide 
The Structure of a Macintosh Application 
Programming Macintosh Applications in Assembly Language 
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ABSTRACT 

Macintosh applications can print information on any variety of printer 
the user has connected to the Macintosh by calling Printing Manager 
routines. Advanced programmers can also call the Printer Driver to 
implement alternate, low-level printing techniques. This manual 
describes the Printing Manager and Printer Driver. 
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ABOUT THIS MANUAL 


Macintosh applications can print information on any variety of printer 
the user has connected to the Macintosh by calling the Printing Manager 
routines in the User Interface Toolbox* Advanced programmers can also 
call the Printer Driver to implement alternate, low-level printing 
techniques. This manual describes the Printing Manager and Printer 
Driver* *** It will eventually become part of the comprehensive Inside 
Macintosh manual* *** 

Like all Toolbox documentation, this manual assumes you*re familiar 
with the Macintosh User Interface Guidelines, Lisa Pascal, and the 
Macintosh Operating System's Memory Manager* You should also be 
familiar with the following: 

~ resources, as described in the Resource Manager manual 

~ the use of QuickDraw, as described in the QuickDraw manual, 
particularly bit images, rectangles, bitMaps, and pictures 

— the use of fonts, as described in the Font Manager manual 

~ the basic concepts of dialogs, as described in the Dialog Manager 
manual 

— files and volumes, as described in the File Manager manual 

— device drivers, as described in the Device Manager manual, *** 
doesn't yet exist *** if you're interested in writing your own 
Printer Driver 

This manual is intended to serve the needs of both Pascal and assembly- 
language programmers* Information of interest to assembly-language 
programmers only is isolated and labeled so that Pascal programmers can 
conveniently skip it* 

The manual begins with an overview of the Printing Manager and what you 
can do with it* It then discusses the basics about printing: the 
various methods of printing available; the relationship between 
printing and the Finder; and the Printing Manager's use of dialogs and 
data structures, the most important of which is the print record* 

Next, a section on using the Printing Manager introduces its routines 
and tells how they fit into the flow of your application* This is 
followed by detailed descriptions of all Printing Manager procedures 
and functions, their parameters, calling protocol, effects, side 
effects, and so on* 

Following these descriptions are sections that won't interest all 
readers* Special information is given about the Printer Driver and the 
format of resource files used when printing, for programmers interested 
in writing their own Printer Driver. 
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Finally, there's a summary of the Printing Manager for quick reference, ^ 

followed by a glossary of terms used in this manual* - 


ABOUT THE PRINTING MANAGER _ 

The Printing Manager is the part of the Macintosh User Interface 
Toolbox that *8 used to print text or graphics on a printer. It's not 
contained in the Macintosh ROM; it must be read from a resource file 
before it can be used. The Printing Manager provides your application 
with: 

- two standard printing methods, and the ability to define two more 

- a standard dialog for the user to specify the paper site and page 
orientation they're using, so you can easily implement a Page 
Setup command in your File menu 

- a standard dialog for the user to specify the method of printing, 
which pages to print, and so on, so you can easily implement a 
Print command in your File menu 

- the ability to perform background processing while the Printing 
Manager is printing 

- a way to abort printing when the user types Command -period 

The Printing Manager is designed such that an application need never be 
concerned with what kind of printer the user has connected to the 
Macintosh; an application uses the same routine calls to print with all 
varieties of printers. 

This printer independence is possible because the Printing Manager uses 
separate, printer-specific code to implement its routines for each 
different variety of printer. While the code for some Printing Manager 
routines (such as those that begin and end printing sessions), is 
contained wholly within the Printing Manager itself, the code for other 
routines (such as those that do the actual printing) depends on the ^ 

printer being used and is contained in a separate printer resource file 
on the user's disk. The Printing Manager dispatches calls to these 
routines, first loading the code into memory if necessary. 

Although the actual routines of the Printing Manager differ for each 
variety of printer, your application uses the same Printing Manager 
calls to print on all varieties of printers. The user "installs" a new 
printer by giving the Printing Manager a new printer resource file to 
work with (Figure 1). Printer installation is transparent to you 
application, and you needn't be concerned with it. 
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Figure 1* Printer Installation 

Each printer resource file also contains a device driver that 
communicates between the Printing Manager and the printer* Because the 
actual routines of the device driver differ for each variety of 
printer , there exists a different device driver for each printer* The 
Printing Manager routines used to call a printer's device driver are 
the same, regardless of printer variety; this manual will refer to the 
device driver of the currently installed printer as the Printer Driver * 

You define the image to be printed by using a printing port , a special 
QuickDraw grafPort customized for printing: 

TYPE TPPrPort “ ‘‘TPrPort; 

TPrPort “ RECORD 

gPort: GrafPort; {grafPort to draw in} 
gProcs: QDProcs; {pointers to drawing routines} 
{more fields for Internal use only} 

END; 

The Printing Manager gives you a printing port when you prepare to 
print a document* You print text and graphics by drawing 
into this port with QuickDraw, just as if you were drawing on the 
screen* The Printing Manager installs its own versions of QuickDraw's 
low-level drawing routines in the printing port, causing your 
higher-level QuickDraw calls to drive the printer instead of drawing 
on the screen. GProcs contains pointers to these low-level drawing 
routines* 

(note) 

To convert a pointer to a printing port into an 
equivalent grafPtr for use with QuickDraw, you can use 
the following variant record type: 
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TYPE TPPort - PACKED RECORD 

CASE INTEGER OF 

0: (pGPort: GrafPtr); 
1: (pPrPort: TPPrPort) 

END; 


METHODS OF PRINTING 


The Printing Manager supports two different methods of printing 
documents: draft and spool. In draft printing , your QuickDraw calls 
are converted directly into command codes the printer understands, 
which are then immediately used to drive the printer* Each element of 
the image is printed as soon as you request it; as you move around to 
various coordinates within the grafPort, the print head moves to the 
corresponding positions on the printed page* Draft printing uses the 
printer's native font and graphics capabilities and probably won't 
produce an image matching the one on the screen* This method of 
printing is more direct than spool printing, but it can also be 
cumbersome, especially for graphics. Draft printing is most 
appropriate for making quick copies of text documents, which are 
printed straight down the page from top to bottom and left to right. 
Depending on the printer and what you're printing, draft printing may 
not even be possible; for instance, not all printers are capable of 
moving the paper backwards (toward the top of the page)* 

Spooling and spool printing are complementary halves of a two-stage 
process* First you cause the Printing Manager to write out (spool) a 
representation of your document's printed image to a disk file* This 
spool file is later read back in, each page is imaged (converted into 
an array of dots at the appropriate resolution), and the result is sent 
to the printer in a single pass from top to bottom. Spool printing 
uses QuickDraw and the Font Manager's graphics and font capabilities to 
produce an image closely matching the one on the screen. 

(note) 

The internal format of spool files is private to the 
Printing Manager and may vary from one printer to 
another. This means that spool files destined for one 
printer can't necessarily be printed on another* In 
spool files for the Imagewriter printer, each page is 
stored in the form of a QuickDraw picture* It's 
envisioned that most other printers will use this same 
approach, but there may be exceptions. 

Spooling and spool printing are two separate stages because spool 
printing a document takes a lot of space — typically from 20K to 40K for 
the printing code, buffers, and fonts, but spooling a document takes 
only about 3K* When spooling a document, large portions of your 
application's code and data may be needed in memory; when spool 
printing, most of your application's code and data are no longer 
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needed* Normally you'll make your printing code a separate program 
segment, so you can swap the rest of your code and data out of memory 
during printing and swap it back in after you're finished. 

If your application can't afford the space required by spool printing, 
it can just perform the spooling stage, and leave the spool file on the 
disk for the user to print later from the Finder (see next section). 

The maximum number of pages in a spool file is defined by the following 
constant *** it may increase *** : 

CONST iPFMaxPgs • 128; {maximum number of pages in a spool file} 


(note) 

Advanced programmers: In addition to draft printing and 
spooling, you can define as many as two more of your own 
methods of document printing for any given printer. (No 
such additional printing methods are currently defined 
for the Imagewriter. ) There are also a number of low- 
level printing methods available, such as bitmap 
printing, text streaming, and screen printing. These 
methods are discussed in the section "Using a Printer 
Driver"* 


Imaging During Spool Printing 

The bit image for a typical page is too big to fit in memory all at 
once* For instance, at the highest resolution of the Imagewriter 
printer (160 dots per inch horizontally by 144 vertically), an 8-by-10 
1 /2-inch page image contains approximately a quarter megabyte of 
information, or twice the total memory capacity of the Macintosh. So 
instead of imaging and printing the entire page at once, the page has 
to be broken into bands small enough to fit in memory. During spool 
printing the Printing Manager actually images each band individually, 
adjusting the fields of the printing port to limit the actual drawing 
to the boundaries of the band. It then prints the resulting bit image 
before Imaging the next band. A page can be broken into bands 
("scanned") in any of four ways. Figure 2 shows the four possible scan 
directions of a printing port* 
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top to bottom 


left to right 





A 

bottom to top 


« 

right to left 






Figure 2. Scan Directions 

The bands are always printed from top to bottom relative to the 
physical sheet of paper; the scan direction determines the 
correspondence between these printed bands and the dots of the image. 
If the long dimension of the paper runs vertically with respect to the 
image , the page is said to be in portrait orientation ; if the long 
dimension runs horizontally, the page is in landscape orientation. In 
practice, portrait pages are normally scanned from top to bottom and 
landscape pages from left to right. 
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PRINTING FROM THE FINDER 


The Macintosh user can choose to print from the Finder as well as from 
an application. Your application should support both alternatives. 

To print a document from the Finder , the user selects the document's 
icon and chooses the Print command from the File menu. When the Print 
command is chosen, the Finder starts up the document's application, and 
passes information to the application indicating that the file is to be 
printed rather than opened. The application is then expected to print 
the document, preferably without doing its entire startup sequence. It 
may choose to do any of the following: 

~ Draft-print the document. 

- Spool the document to a file and then print it iomediately. 

— Spool the document to a file and leave it for the user to print 
later via the Printer program (descibed below). 

If your application writes spool files on a disk and then doesn't spool 
print them, it's up to the user to print them. The user simply selects 
the spool file's icon (Figure 3) and chooses the Print command from the 
File menu. When the Print command is chosen, the Finder starts up a 
special program called Printer , which spool prints spool files. It's 
provided as a utility for use with programs that don't do their own 
spool printing. Its main purpose is to read a spool file, image it, 
and print it. 


& 0 

Printer Prfcrt F«e 

Figure 3. Icons for the Printer Program and Spool Files 

Spool files can be identified by their file type and creator: 

CONST lPfType » $5046484C; {spool file type 'PFIL'} 

lPfSig • $50535953; {spool file creator 'PSYS'} 


(note) 

The details of the Finder interface are discussed in The 

Structure of a. Macintosh Application . 

*** This method of spool printing may be temporary. Currently, the 
easiest way for your application to do printing is to leave spool files 
on the disk and rely on the user to print them via Printer. Eventually 
Printer may be eliminated and one of the following solutions will be 
employed: The process will remain the same, and the code of Printer 
will be integrated into the Finder; or your application will be 
required to do spool printing itself. *** 
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PRINT RECORDS AND DIALOGS 




For every printing operation , your application needs to determine the 
following: 

- the resolution and other characteristics of the printer being used 

- the dimensions of the printed image and of the physical sheet of 
paper 

- the printing method to be used (draft or spool) 

- the name of the spool file, if applicable 

- which pages of the document to print 

- how many copies to print 

- an optional background procedure to be run during idle times in 
the printing process (discussed later) 

This information is contained in a data structure called a print 
record * The Printing Manager fills in most of the print record for 
you* Some values depend on the variety of printer installed in the 
Printing Manager; others are set as a result of dialogs with the user. 

(note) 

Whenever you save a document, it's recommended that you 
write an appropriate print record in the document's file 
(see the "Printing Resources" section)* This allows the 
document to "remember" its own printing parameters for 
use the next time it's printed. 

(note) 

If you try to use a print record that's invalid for the 
current version of the Printing Manager or for the 
printer installed in the Printing Manager, the Printing 
Manager will correct the record by filling it with 
default values* 

The Information in the print record that can vary from one printing job 
to the next is obtained from the user by means of dialogs* The 
Printing Manager uses two standard dialogs for this purpose. The style 
dialog includes the paper size and page orientation (Figure 4). This 
dialog is conventionally associated with a Page Setup command in the 
application. 
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H Paper f (IS Letter 

O *4 Letter 

f «( ') 

H O US Legal 

O International Fanfold 


1 Orientation: Q Tall 

O Tall lid jutted O Wide 

[ Cancel ] 


Figure 4. The Standard Style Dialog 


The job dialog , normally associated with the application's Print 
command, requests information on how to print the document this time, 
such as the method of printing (draft or spool), the print quality (for 
printers that offer a choice of resolutions), the type of paper feed 
(such as fanfold or cut-sheet), the range of pages to be printed, and 
the number of copies (Figure 5)* 


Quality: 

OHigh 

® Standard O Draft 

[ or ] 

Page Range: 

® Bll 

O From: | Ta: \ { 


Copies: 

jf | 



Paper Feed: 

<§) Continuous 

O Cut Sheet 

[ Cancel ] 


Figure 5. The Standard Job Dialog 


Print records are referred to by handles* Their structure is as 
follows : 


TYPE THPrint 
TPPrint 
TPrint 


‘TPPrint; 

‘TPrint ; 

RECORD 

iPrVersion: 

prlnfo: 

rPaper : 

prStl: 

prlnfoPT: 

prXInfo: 

prJob: 

printX: 

END; 


INTEGER; {Printing Manager version} 
TPrlnfo; {printer information} 

Rect; {paper rectangle} 

TPrStl; {style information} 

TPrlnfo; {copy of prlnfo} 

TPrXInfo; {band information} 

TPrJob; {job information} 

ARRAY [1**19] OF INTEGER 

{used internally} 


IPrVersion identifies the version of the Printing Manager that 
initialized this print record* 

Most of the other fields of the print record are "subrecords" 
containing various parts of the overall printing information; these are 
discussed in separate sections below. 
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Assembly-language note ; The global constant IPrintSlze equals 
the length in bytes of a print record* 


The Printer Information Subrecord 


The printer information subrecord (field prlnfo of the print record) 
describes the characteristics of the particular printer you're using* 
ItB contents are set by the Printing Manager when it initializes the 
print record* All applications will need to refer to the information 
it contains* (The prlnfoPT field of the print record is a copy of the 
prlnfo field and is used internally by the Printing Manager during 
printing.) 

The printer information subrecord is defined as follows: 

TYPE TPrlnfo - RECORD 

iDev: INTEGER; {driver information) 
iVRes: INTEGER; {printer vertical resolution) 
iHRes: INTEGER; {printer horizontal resolution) 
rPage: Rect {page rectangle) 

END; 

The iDev field contains information used by QuickDraw and the Font 
Manager for selecting fonts for the printer. The high-order byte is 
the reference number of the Printer Driver, -3. The low-order byte 
contains device-specific information on how the printer is being used. 
For example, for the Imagewriter printer, bit 0 specifies high (1) or 
low (0) resolution and bit 1 specifies portrait (1) or landscape (0) 
orientation. 

(note) 

If you store thi6 word into the device field of a 
grafPort, you can use the QuickDraw routines CharWidth, 
StringVidth, TextWidth, and GetFontlnfo to ask for 
information about a font drawn on that device. 

IVRes and iHRes give the vertical and horizontal resolution of the 
printer, in dots per inch. 

RPage is the page rectangle . representing the boundaries of the 
printable page. Its top left corner always has coordinates (0,0); the 
coordinates of the bottom right corner give the maximum page height and 
width attainable on the given printer, in dots. Typically these are 
slightly less than the physical dimensions of the paper, because of the 
printer's mechanical limitations. 

The results of the style dialog conducted with the user determine the 
values of the iVRes, iHRes, and rPage fields. For example, with the 
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Imagewriter printer, the style dialog's three orientation buttons yield 
the following: 


Dutton 

Orientation 

IVRes 

IHRes 

Tall 

Portrait 

80 

72 

Tall adjusted 

Portrait 

72 

72 

Wide 

Landscape 

72 

72 


The physical paper size is given by the rPaper field of the print 
record* This paper rectangle is outside of the page rectangle: it 
defines the physical boundaries of the paper in the same coordinate 
system as rPage (see Figure 6)* Thus the top left coordinates of the 
paper rectangle are typically negative and its bottom right coordinates 
are greater than those of the page rectangle. 



Figure 6. Page and Paper Rectangles 


The Style Subrecord . 

The style subrecord (field prStl of the print record) describes the 
type and size of paper used in the printer* The contents of the style 
subrecord are normally set by the Printing Manager after dialogs with 
the user, and only advanced programmers need be concerned with them. 

The style subrecord is defined as follows: 
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TYPE TPrStl 


RECORD 

wDev: TWord; 

iPageV: INTEGER; 
iPageH: INTEGER; 
bPort : Signed By te ; 
feed : TFeed 

END; 


{used internally) 

{paper height) 

{paper width) 

{printer or modem port) 
{paper type) 


IPageV and iPageH give the physical dimensions of the paper, in 120ths 
of an inch. The user can set them by choosing a standard paper size 
(such as U. S. Letter, U. S. Legal, or European A4) from the style 
dialog. The number of units per inch is defined by the following 
constant: 


CONST IPrPgFract “ 120; {units per inch of paper dimension) 

BPort designates which port on the back of the Macintosh the printer is 
connected to: 0 for the printer port, 1 for the modem port. *** 
Currently the Printing Manager ignores this value, and instead uses the 
global variable sPPrint. *** 

Feed identifies the type of paper feed being used: 

TYPE TFeed ■ (feed Cut, {hand -fed, individually cut sheets) 

feedFanfold, {continuous-feed fanfold paper) 
feedMechCut, {mechanically fed cut sheets) 
feedOther); {other types of paper) 

The user sets this field by choosing Continuous or Cut Sheet from the 
job dialog. When Cut Sheet is chosen, the printer will pause at the 
end of each page and a dialog box will prompt the user to insert the 
next sheet. 






The Job Subrecord 


The job subrecord (field prJob of the print record) contains 
information about a particular printing job. Its contents are normally 
set by the Printing Manager as a result of a job dialog with the user. 

The job subrecord is defined as follows: 


TYPE TPrJob 


RECORD 
iFstPage: 
iLstPage: 
iCopies : 
bJDocLoop: 
f FromUsr : 
pldleProc: 
pFileName: 
iFileVol: 
bFi leVers: 
bJobX: 

END; 


INTEGER; 

INTEGER; 

INTEGER; 

SignedByte; 

BOOLEAN; 

ProcPtr; 

TPStr80; 

INTEGER; 

SignedByte; 

SignedByte 


{first page to print) 

{last page to print) 

{number of copies) 

{printing method) 

{TRUE if called from application) 
{background procedure) 

{spool file name) 

{volume reference number) 

{version number of spool file) 
{not used) 
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TPStr80 » ~TStr80; 

TScr80 - STRING [80]; 

Most programmers need only be concerned with the bJDocLoop , pFileName , 
and pldleProc fields* BJDocLoop represents the method of printing to 
use* The user sets this field by choosing High, Standard, or Draft 
from the job dialog* BJDocLoop should be one of the following 
predefined constants: 

CONST bDraftLoop * 0; {draft printing} 

bSpoolLoop ■ 1; {spooling} 

bUserlLoop - 2; {printer-specific, method 1} 

bl)ser2Loop ■ 3; {printer-specific, method 2} 

If you're spool printing, it's a good idea to give each file you spool 
to the disk a different name, in the pFileName field, so that it 
doesn't overwrite any other spool files on the disk. PFileName is 
initialized to NIL, denoting the default file name found in the printer 
resource file* *** (Currently the default file name is 'Print 
File'.) *** 

IFstPage and iLstPage designate the first and last pages to be printed* 
The Printing Manager knows nothing about any page numbering placed by 
an application within a document, and always considers the first 
printable page to be page 1. For example, if IFstPage is 2, the 
Printing Manager will print the second page in the document, regardless 
of how the page is actually numbered* If you're draft printing, you'll 
need to use the value of iCopies to determine the number of copies to 
print (the Printing Manager automatically handles multiple copies for 
spooling). 

FFromUsr is TRUE when the Printing Manager is called from an 
application program, FALSE when it's called from the Printer program. 
PldleProc is a pointer to the background procedure (explained below) 
for this printing operation. In a newly initialized print record this 
field is set to NIL, designating the default background procedure. 

This procedure just polls the keyboard and cancels further printing if 
the user types Command -period. You can install a background procedure 
of your own by storing directly into the pldleProc field. 

For spooling operations, IFileVol and bFileVers are the volume 
reference number and version number of the spool file. IFileVol and 
bFileVers are both initialized to 0 . You can override the default 
settings by storing directly into these fields. 
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The Band Information Subrecord 


The band information subrecord (field prXlnfo of the print record) 
contains information about the way a page will be imaged during spool 
printing* Its contents are set by the Printing Manager , and most 
programmers needn't be concerned with it* 


The band information subrecord is defined as follows: 


TYPE TPrXlnfo - RECORD 

iRowBy tes : 
IBandV : 
iBandH: 
iDevBytes: 
i Band 6 : 
bPat Scale: 
bUl Thick: 
bUlOffset: 
bUl Shadow: 
.scan: 
bXlnfoX: 

END; 


INTEGER; 

INTEGER; 

INTEGER; 

INTEGER; 

INTEGER; 

Signed Byte; 

SignedByte; 

Signed Byte ; 

SignedByte; 

TScan; 

SignedByte 


(bytes per row} 
(vertical dots) 
(horizontal dots} 
(size of bit image} 
(bands per page} 

(used by QuickDraw} 
(underline thickness} 
(underline offset} 
(underline descender} 
(scan direction} 

(not used} 


IRowBy tes is the number of bytes in each row of the band's bit image, 
IBandV and IVBandH are the dimensions of the band in dots, IDevBytes is 
the number of bytes of memory needed to hold the bit image, and iBands 
1 b the number of bands per page* 


BPatScale is used by QuickDraw when it scales patterns to the 
resolution of the printer* BUlThick, bUlOffset, and bUlShadow are used 
for underlining text; they stand for the thickness of the underline, 
its offset below the base line, and the width of the break around 
descenders, all in dots* The scan field specifies the scan direction 
for banding as a value of type TScan: 

TYPE TScan • (scanTB, (scan top to bottom} 
scanBT, (scan bottom to top} 
scanLR, (scan bottom to top} 
scanRL); (scan right to left} 








BACKGROUND PROCESSING 

As mentioned above, the Job subrecord includes a pointer, pldleProc, to 
an optional background procedure to be run whenever the Printing 
Manager has directed output to the printer and is waiting for the 
printer to finish* The background procedure takes no parameters and 
returns no result; the Printing Manager simply runs it at every 
opportunity* There's no limit to the length of time that a background 
procedure can execute, but beyond a certain length of time printing 
will be slowed* 
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If you don't designate a background procedure, the Printing Manager 
vill use one by default that ju6t polls the keyboard and cancels 
further printing if the user types Command -period* In this case you 
should display an alert box to inform the user that the Command -period 
option is available* It '6 suggested, however, that instead of relying 
on this method, you supply your own background procedure to give the 
user a more convenient way to cancel printing. For instance, you might 
put up a dialog box with a Cancel button the user can click with the 
mouse; or, in a background procedure that runs your application, you 
might replace the Print command with Stop Print. 

While printing from a 6pool file, the Printing Manager maintains a 
printer status record in which it reports on the progress of the 
printing operation: 

TYPE TPrStatus - RECORD 


iTotPages : 

INTEGER; 

{total number of pages} 

i Cur Page : 

INTEGER; 

{page being printed} 

iTotCopies: 

INTEGER; 

{number of copies} 

iCurCopy : 

INTEGER; 

{copy being printed} 

iTotBands : 

INTEGER; 

{bands per page} 

i Cur Band : 

INTEGER; 

{band being printed} 

fPgDirty: 

BOOLEAN; 

{TRUE if started printing page} 

f Imaging: 

BOOLEAN; 

{TRUE if imaging} 

hPrint : 

THPrint; 

{print record} 

pPrPort: 

TPPrPort ; 

{printing port} 

hPic: 

Pic Handle 

{used internally} 


END; 


FPgDirty is TRUE if anything has been printed yet on the current page, 
FALSE if not; f Imaging is TRUE while a band is being imaged, FALSE 
while it's being printed. 'HPrint is a handle to the print record for 
this printing operation; pPrPort is a pointer to the printing port. 

Your background procedure can use this information — for example, to 
display a progress report on the screen ("Now printing copy 3 of 5, 
page 7 of 12"). 

(note) 

The Printing Manager only calls your background procedure 
while it's printing. If you want your background 
procedure to execute during spooling, you'll have to call 
it yourself. 

Advanced programmers can use background processing in a variety of 
useful way 8. For example, with a background procedure that performs 
one pass through your main program loop, you can achieve the effect of 
concurrent printing. That is, your application can continue to run 
while the printing is taking place, although there stay be some 
degradation in performance. The user is given the illusion that the 
printing is going on "in the background" behind the application. (In 
reality, of course, it's the application that's running in the 
background behind the printing task.) 
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(warning) 

You have to be careful in the way you write your 
background procedure, to avoid a number of subtle 
concurrency problems that may arise* For instance, if 
the background procedure uses QuickDraw, it must be sure 
to restore the printing port as the current port before 
returning* It's particularly important not to attempt 
any printing from within the background procedure: the 
Printing Manager is mot reentrant I If you use a 
background procedure that runs your application 
concurrently with printing, it should disable all menu 
items having to do with printing, such as Page Setup and 
Print* 




USING THE PRINTING MANAGER 


This section discusses how the Printing Manager routines fit into the 
general flow of your program and gives you an idea of which routines pm ^ 

you'll need to use* The routines themselves are described in detail in 
the next section. 

To use the Printing Manager, you must have previously initialized 
QuickDraw, the Font Manager, the Window Manager, the Menu Manager, 

TextEdit, and the Dialog Manager. The first Printing Manager routine 
to call is PrOpen, which opens the printer resource file. The last 
routine to call is PrClose, which closes the Printer Driver and the 
printer resource file* 

(note) 

PrOpen and PrClose are meant to be called once each, at 
the beginning and end of your application. However, if 
space is particularly critical, you may prefer to bracket 
every Printing Manager call with a PrOpen and a PrClose* 

This frees the space occupied by various Printing Manager 
data structures when they're not in use* 

Before printing a document, you need a properly filled out print 
record. You can either use an existing print record (for instance, 
from a document) or initialize one to the current default settings by 
calling PrintDefault* If you use an existing print record, you should 
call PrValidate to make sure it's valid for the current version of the 
Printing Manager and for the currently installed printer* 

When the user chooses the Page Setup commmand, call PrStlDialog to ask 
about the paper size and page orientation* From the printer 
information subrecord you can then determine where each page break 
occurs* 

When the user chooses the Print commmand, call PrJobDialog to ask the 
user for specific information about that printing job* To apply the 
results of one job dialog to several documents (when printing from the 
Finder, for example), call PrJobMerge. 
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To draft print or spool a document, begin by calling PrOpenDoc, which 
returns a printing port customized for draft printing or spooling 
(depending on the bJDocLoop field of the Job subrecord). You can then 
print or spool your document by "drawing" into this printing port with 
QuickDraw, using the values in the printer information subrecord to 
adjust for the parameters of the printer. Call PrOpenPage and 
PrClosePage at the beginning and end of each page, and PrCloseDoc at 
the end of the entire document. Each page is either printed 
immediately (draft printing) or written to the disk as part of a spool 
file (spooling). 

To print a spool file, swap as much of your program out of memory as 
you can, and then call PrPicFile. 

Call PrError to check for errors caused by a Printing Manager routine. 
To cancel a printing operation in progress, use PrSetError. Be sure to 
call PrCloseDoc or PrClosePage after you cancel printing in progress. 


PRINTING MANAGER ROUTINES 


This section describes the procedures and functions that make up the 
Printing Manager. They're presented in their Pascal form; for 
information on using them from assembly language, see Programming 
Macintosh Applications in Assembly Language . 


Initialization and Termination 


PROCEDURE PrOpen; 

PrOpen prepares the Printing Manager for use. It opens the Printer 
Driver and the printer resource file. If either of these items is 
missing, or if the printer resource file is not properly formed, PrOpen 
will do nothing, and PrError will return a Resource Manager result 
code. 


PROCEDURE PrClose ; 

PrClose releases the memory used by the Printing Manager. It closes 
the printer resource file, allowing the file's resource map to be 
removed from memory. It *** currently *** doesn't close the Printer 
Driver, however, since the driver may have been opened before the 
PrOpen call was issued. 
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Print Records and Dialogs 


PROCEDURE PrintDefault (hPrint: THPrint); 

Print Default fills the fields of a print record with the current 
default values stored in the printer resource file* HPrint is a handle 
to the record, which may be a new print record that you've just 
allocated or an existing one (from a document, for example)* 


FUNCTION Pr Validate (hPrint: THPrint) : BOOLEAN; 

PrValidate checks the contents of a print record for compatibility with 
the current version of the Printing Manager and with the installed 
printer* If the record is valid, the function returns FALSE (no 
change); if invalid, the record is adjusted to the current default 
values, taken from the printer resource file, and the function returns 
TRUE. 

PrValidate also updates the print record to reflect the current 
gettings in the style and job subrecords* These changes have no effect 
on the function's Boolean result. 


FUNCTION PrStlDialog (hPrint: THPrint) : BOOLEAN; 

PrStlDialog conducts a style dialog with the user to determine the 
paper size and paper orientation being used* The initial settings 
displayed in the dialog box are taken from the current values in the 
print record* If the user confirms the dialog, the results of the 
dialog are saved in the print record and the function returns TRUE; 
otherwise the print record is left unchanged and the function returns 
FALSE. 

(note) 

If the print record was taken from a document, you should 
update its contents in’ the document's file if PrStlDialog 
returns TRUE. This makes the results of the style dialog 
"stick" to the document. 


FUNCTION PrJobDialog (hPrint: THPrint) : BOOLEAN; 

PrJobDialog conducts a job dialog with the user to determine the 
printing quality, number of pages to print, and so on* The initial 
settings displayed in the dialog box are taken from the current values 
in the print record. If the user confirms the dialog, both the print 
record and the printer resource file are updated (so that the user's 
choices "stick" to the printer) and the function returns TRUE; 
otherwise the print record and printer resource file are left unchanged 
and the function returns FALSE* 
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(note) 

If the job dialog is associated with your application's 
Print command, you should proceed with the requested 
printing operation if PrJobDialog returns TRUE. If the 
print record was taken from a document, you should update 
its contents in the document's file. 


PROCEDURE PrJobMerge (hPrintSrc,hPrintDst: THPrint); 

PrJobMerge copies the job subrecord from one print record (hPrintSrc) 
to another (hPrintDst) and updates the destination record's printer 
information, band information, and paper rectangle, based on 
information in the job subrecord. This allows the information in the 
job subrecord to be used for a group of related jobs. 


Draft Printing and Spooling 


FUNCTION PrOpenDoc (hPrint: THPrint; pPrPort: TPPrPort; pIOBuf: Ptr) 

: TPPrPort; 

PrOpenDoc initializes a printing port for use in printing a document, 
makes it the current port, and returns a pointer to it. HPrint is a 
handle to the print record for this printing operation. The printing 
port is customized for draft printing or spooling, depending on the 
setting of the bJDocLoop field in the job subrecord. For spooling, the 
spool file's name, volume reference number, and version number are 
taken from the job subrecord. 

PPrPort is a pointer to the storage to be used for the printing port. 

If this parameter is NIL, PrOpenDoc will allocate a new printing port 
for you. Similarly, pIOBuf points to an area of memory to be used as 
an input/output buffer; if it's NIL, PrOpenDoc will use the volume 
buffer for the spool file's volume. 

(note) 

The pPrPort and pIOBuf parameters are provided because 
both the printing port and the input/output buffer are 
nonrelocatable objects. To avoid cluttering the heap 
with such objects, you have the opportunity to allocate 
them yourself and pass them to PrOpenDoc. Most of the 
time you'll just set both of these parameters to NIL. 

(note) 

Newly created printing ports use the system font (since 
they're grafPorts), but newly created windows use the 
application font. Be sure the font you use in the 
printing port is the same as the font in your application 
window if you want the text in both places to match. 
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PROCEDURE PrOpenPage (pPrPort: TPPrPort; pPageFrame: TPRect); 

PrOpenPage begins a new page in the document associated with the given 
printing port* The page is printed only if it falls within the page 
range designated in the job aubrecord. 

For spooling, the pPageFrame parameter points to a rectangle that will 
be used as the QuickDraw picture frame for this page: 

TYPE TPRect « ~Rect; 

When the spool file is later printed, this rectangle will be scaled 
(via the QuickDraw DrawPicture procedure) to coincide with the page 
rectangle in the printer information subrecord. Unless you want the 
printout to be scaled, you should set pPageFrame to NIL — this uses the 
current page rectangle as the picture frame, and the page will be 
printed with no scaling. 


PROCEDURE PrClosePage (pPrPort: TPPrPort); 

PrClosePage finishes up the current page of the document associated 
with the given printing port. For draft printing, it ejects the page 
from the printer and, if necessary, alerts the U6er to insert another; 
for spooling, it closes the picture representing the current page* 


PROCEDURE PrCloseDoc (pPrPort: TPPrPort); 

PrCloseDoc finishes up the printing of the document associated with the 
given printing port. For draft printing, it issues a form feed and a 
reset command to the printer; for spooling, it closes the file if the 
spooling was successfully completed or deletes it the file if the 
spooling was unsuccessful. 


Spool Printing 


PROCEDURE PrPicFile (hPrint: THPrint; pPrPort: TPPrPort; pIOBuf: Ptr; 
pDevBuf : Ptr; VAR pr Status: TPrStatus); 

PrPicFile images and prints a spool file. HPrint is a handle to the 
print record for this printing operation. The name, volume reference 
number, and version number of the spool file will be taken from the job 
subrecord of this print record. After printing is successfully 
completed, the Printing Manager deletes the spool file from the disk. 

PPrPort is a pointer to the storage to be used for the printing port 
for this operation. If this parameter is NIL, PrPicFile will allocate 
its own printing port. Similarly, pIOBuf points to an area of memory 
to be used as an input/output buffer for reading the spool file; if 
it's NIL, PrPicFile will use the volume buffer for the spool file’s 
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volume. PDevBuf points to a similar buffer (the "band buffer") for 
holding the bit image to be printed; if NIL, PrPicFile will allocate 
its own buffer from the heap. As for PrOpenDoc, you'll normally want 
to set all of these storage parameters to NIL. 

(note) 

If you provide your own storage for pDevBuf, it has to be 
big enough to hold the number of bytes indicated by the 
iDevBytes field of the TPrXInfo subrecord of the print 
record. 

(warning) 

Be sure not to pass , in pPrPort , a pointer to the same 
printing port you received from PrOpenDoc, the one you 
originally used to 6pool the file. If that earlier port 
was allocated by PrOpenDoc itself (that is, if the 
pPrPort parameter to PrOpenDoc was NIL), then PrCloseDoc 
will have disposed of the port, making your pointer to it 
invalid. PrPicFile initializes a fresh printing port of 
its own; you just provide the storage (or let PrPicFile 
allocate it for itself). Of course, if you earlier 
provided your own storage to PrOpenDoc, there's no reason 
you can't u6e the same storage again for PrPicFile. 

The prStatus parameter is a printer status record that PrPicFile will 
use to report on its progress. Your background procedure (if any) can 
use this record to monitor the state of the printing operation. 


Handling Errors 


FUNCTION PrError : INTEGER; [Pascal only] 

PrError returns the result code returned by the last Printing Manager 
routine. The possible result codes are: 

CONST noErr * 0; {no error) 

IMemFullErr ■ -108; {not enough heap space} 

and any Resource Manager result code. A result code of iMemFullErr 
means that the Memory Manager was unable to fulfill a memory allocation 
request by the Printing Manager. 


PROCEDURE PrSetError (iErr: INTEGER); [Pascal only] 

PrSetError stores the specified value into the global variable where 
the Printing Manager keeps its result code. The main *** (currently 
the only) *** use of this procedure is for canceling a printing 
operation in progress. To do this, write 
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Pr Se tError ( iPr Abort ) 

where iPrAbort i6 the following predefined constant: 

CONST iPrAbort « 128; {result code for halting printing} 


Assembly-language note : You can achieve the same effect as 
PrSetError by storing directly into the location specified by 
print Vars+iPrErr. *** Currently you shouldn't store into this 
location if it already contains an nonzero value* *** 


Low-Level Driver Access 


The routines in this section are used for communicating directly with 
the Printer Driver; the Printer Driver itself is described in the next 
section* You'll need to be familiar with the Device Manager to use the 
information given in this section. 


PROCEDURE PrDrvrOpen; 

PrDrvrOpen opens the Printer Driver. 


PROCEDURE PrDrvrClose; 

PrDrvrClose closes the Printer Driver* 


PROCEDURE PrCtlCall (iVhichCtl: INTEGER; lParaml ,lParam2,lParam3: 
Longlnt); 

PrCtlCall calls the Printer Driver's control routine. IWhichCtl 
designates the operation to be performed; the rest of the parameters 
depend on the operation. 




FUNCTION PrDrvrDCE : Handle; 

PrDrvrDCE returns a handle to the Printer Driver's device control 
entry. 


FUNCTION PrDrvrVers : INTEGER; 

PrDrvrVers returns the version number of the Printer Driver in the 
system resource file. 
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The version number of the Printing Manager is available as the 
predefined constant iPrRelease. You may want to compare the result of 
PrDrvrVers with iPrRelease to see if the Printer Driver in the resource 
file is the most recent version* 


PROCEDURE PrNo Purge ; 

PrNoPurge prevents the Printer Driver from being purged from the heap* 


PROCEDURE Pr Purge; 

PrPurge allows the Printer Driver to be purged from the heap* 


THE PRINTER DRIVER 


This section describes the Printer Driver, the device driver that 
communicates with a printer via the printer port or the modem port. 

Only programmers interested in low-level printing or writing their own 
device driver need read this* You'll need to be familiar with the 
Device Manager manual to use most of this information and the low-level 
routines described above* 

The printer resource file for each variety of printer includes a device 
driver for that printer. When a particular printer is installed in the 
Printing Manager, the printer's device driver is copied from the 
printer resource file into the system resource file, making it the 
active Printer Driver. 

The Printer Driver responds to the standard Device Manager calls 
OpenDriver, CloseDriver, Control, and Status. You can also communicate 
with it via the Printing Manager routines PrDrvrOpen, PrDrvrClose, and 
PrCtlCall. (The Status call i6 normally used only by the Font 
Manager*) Its driver name and driver reference number are available as 
the following predefined constants: 

CONST sPrDrvr ‘ « '.Print'; {Printer Driver resource name} 

iPrDrvrRef “ -3; {Printer Driver reference number} 

To open the Printer Driver, call PrDrvrOpen; it'll remain open until 
you call PrDrvrClose. Calling PrNoPurge will prevent the driver from 
being purged from the heap until you call PrPurge. 

You can call the PrDrvrVers function to determine whether the printing 
resources stored in the system resource file are compatible with the 
version of the Printing Manager you're using* 

To get a handle to the driver's device control entry, call PrDrvrDCE. 

By calling the driver's control routine with PrCtlCall, you can perform 
a number of low-level printing operations such as bitmap printing, 
screen printing, and direct streaming of text to the printer (described 
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below). The first parameter to PrCtlCall, iWhichCtl, identifies the 
operation you want. The following values are predefined: 

CONST IPrBitsCtl " 4; {bitMap printing) 
iPrlOCtl • 5; {text streaming) 
iPrEvtCtl ■ 6; {screen printing) 
iPrDevCtl ■ 7; {device control) 
iFMgrCtl * 8; {used by the Font Manager) 

The remaining parameters of PrCtlCall — lParaml, lParam2 , and lParam3 — 
are three long integers whose meaning depends on the operation, as 
described below. 


BitMap Printing 

To send all or part of a bitMap directly to the printer, use PrCtlCall 
with iWhichCtl - IPrBitsCtl. Parameter lParaml is a pointer to a 
QuickDraw bitMap; lParam2 is a pointer to the rectangle to be printed, 
in the coordinates of the printing port. 

LParam3 is a printer^dependent parameter. On the Imagewriter it's used 
to control the printer's aspect ratio (the ratio of horizontal to 
vertical resolution). In low resolution, the Imagewriter normally 
prints 80 dots per inch horizontally by 72 vertically. This produces 
rectangular dots that are taller than they are wide. Since the 
Macintosh screen has square pixels (72 per inch both horizontally and 
vertically), images printed on the Imagewriter don't look exactly the 
same as they do on the screen. 

To address this problem, the Imagewriter has a special square-dot mode 
that alters the speed of the print head to produce 72 dots per inch 
horizontally instead of 80. Printing in this mode is slower than in 
the normal mode, but gives a more faithful reproduction of what the 
user sees on the screen. The user can choose which of the two modes to 
use by using the Printer program. 

The value of the lParam3 parameter should be one of the following 
predefined constants: 

CONST IScreenBits *0; {configurable) 

IPaintBits - 1; {72 by 72 dots) 

LScreenBits tells the Printer Driver to honor the user's selection 
between rectangular and square dots; IPaintBits overrides the user's 
choice and forces square dots. 

Putting all this together, you can print the entire screen at the 
user's chosen aspect ratio with 

PrCtlCall(iPrBitsCtl, ORD(flscreenBits) , 

ORD(@screenBits.bounds) , IScreenBits) 
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To print the contents of a single window in square dots, use 

PrCtlCall(iPrBitsCtl, ORD( @the Window*. por tBi ts ) , 

ORD(@theWindow*.portRect), IPaintBits) 


Text Streaming ’ 

Text streaming is useful for fast printing of text when speed 16 more 
important than fancy formatting or visual fidelity. It gives you full 
access to the printer's native text facilities, such as control or 
escape sequences for boldface, italic, underlining, or condensed or 
expanded type, but makes no use of QuickDraw's elaborate formatting 
capabilities. 

(warning) 

Relying on specific printer capabilities and control 
sequences will make your application printer-dependent. 

You can send a stream of text characters directly to the printer with 
iWhichCtl ■ iPrIOCtl. LParaml is a pointer to the beginning of the 
text; lParam2 is the number of bytes to transfer (a long integer); 
lParam3 is a pointer to an optional background procedure, or NIL for 
none. 

IPrDevCtl is used for various printer control operations. When 
streaming text to the printer, you can use iPrDevCtl to perform these 
general operations in a printer-independent way, letting the Printer 
Driver take care of the details for a specific printer. The lParaml 
parameter specifies the operation you want: 

CONST IPrReset - $00010000; (reset printer) 

IPrPageEnd - $00020000; (start new page) 

IPrLineFeed - $00030000; (start new line) 

Before starting to print a document with text streaming, use 

PrCtlCall( iPrDevCtl , IPrReset, 0, 0) 

to reset the printer to its standard initial state. The parameters 
lParam2 and lParam3 are meaningless and should be set to 0. 

At the end of each printed line, 

PrCtlCalK iPrDevCtl, IPrLineFeed, 0, 0) 

advances the paper one line and returns to the left margin. This 
achieves the effect of the standard "CRLF" (carriage-return-line-feed) 
sequence in a printer— independent way. It's strongly recommended that 
you use this method instead of sending carriage returns and line feeds 
directly to the printer. The lParam2 parameter tells how far to 
advance the paper; lParam3 is meaningless and should be set to 0. 

*** The exact use of lParam2 in this call hasn't yet been determined. 
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A value of 0 will probably denote the printer's standard line height, 
which is usually what you'll want* *** 

At the end of each page, 

PrCtlCallCiPrDevCtl, IPrPageEnd, 0, 0) 

does whatever is appropriate for the given printer, such as sending a 
form feed character and advancing past the paper fold* It's 
recommended that you use this call instead of just sending a form feed 
yourself* LParam2 and !Param3 are meaningless and should be set to 0. 


Screen Printing 

IPrEvtCtl does an immediate dump of all or part of the screen directly 
to the printer* LParaml is one of the following codes: 

CONST iPrEvtAll - S0002FFFD; {print whole screen} 

iPrEvtTop - S0001FFFD; {print top (frontmost) window} 

The other two parameters are meaningless and should be set to 0* So, 
for example, 

PrCtlCalKiPrEvtCtl, iPrEvtAll, 0, 0} 
prints the entire screen at the user's chosen aspect ratio, and 
PrCtlCalKiPrEvtCtl, iPrEvtTop, 0, 0) 
prints just the frontmost window* 

The Operating System Event Manager uses this call to do immediate 
screen printing when the user types a special key combination 
(Command-$ for the frontmost window, the same with Caps Lock for the 
full screen)* 


Font Manager Support 

The Printer Driver provides one Status and one Control call for use by 
the Font Manager in selecting fonts for a given printer* Both are 
identified by the following csCode value 

CONST IFKgrCtl - 8; 

With the Status call, the Font Manager asks for the printer's font 
characterisation table* After using the information in this table to 
select a font, it issues the Control call to give the Printer Driver a 
chance to modify the choice* This process is described further in the 
Font Manager manual* 


6/11/84 Che rnicoff -Hacker 


/PRINTING/PRINT. D 


PRINTING RESOURCES 


29 


PRINTING RESOURCES 


For programmers who want to write their own device drivers for 
different printers or modify existing drivers, this section describes 
the two files that contain the resources needed to run the Printing 
Manager: the system resource file and. the printer resource file (see 
Figure 7). Most of the data described in this section is accessible 
only to assembly-language programmers* 


System resource file 


printer resource file name 


device (friver (copy) 


driver's private data 
storage (copy) 


^ Printer resource file 


device driver (original) 


driver's private data 
storage (original) 


printer-specific code 


default print record 


last print r e cord 


default spool file name 


dialogs and alerts 


Figure 7 • Printing Resources 
The system resource file contains: 


Resource 

Resource type 

Resource ID 

Name of the current printer 
resource file 

•STR ' 

$£000 

A copy of the device driver for 
the currently installed printer 

'DRVR' 

2 

A copy of the driver's private 
data storage 

'PREC' 

2 


The printer resource file contains the following information: 
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Resource 

The device driver for this 
printer 

Resource type 
•DRVR' 

Resource ID 
$E000 

The driver's private storage 

•PREC' 

$E000 

Printer-specific code used to 
implement Printing Manager 
routines 

, 'PDEF' 

0 through 6 
(see below) 

Default print record for use 
with this printer 

'PREC' 

0 

Print record from the previous 
printing operation 

•PREC' 

1 

Default spool file name 

•STR ' 

$E001 

Style dialog 

•dlog' 

$E000 

Job dialog 

•dlog' 

$E001 

Installation dialog 

•dlog' 

$E002 

Alerts 

'ALRT' 

(private) 

Dialog and alert item lists 

'DITL' 

(private) 


Notice that the Printer Driver and its private storage are kept in both 
the system and printer resource files* The copies in the system 
resource file are the one6 actually used; those in the printer resource 
file are there just to be copied into the system resource file when a 
new printer is installed* Installing a new printer is done by copying 
the driver and its private storage from the printer resource file to 
the system resource file and placing the name of the printer resource 
file in the system resource file* (You can use this method to install 
a printer yourself , but normally it's done by the Printer program at 
the user's request*) 

You can use the following predefined constants to identify the various 
resource types and IDs in the printer resource file (they'll be 
different in the system resource file): 
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CONST IPrintType - $50524543; 

IPrintDef - 0; 
IPrintLst “ 1 ; 
iPrintDrvr “ 2; 


IMyPrDrvr - $E000; 


{type ('PREC') for print records and ) 

{ private storage) 

{ID for default print record) 

{ID for previous print record) 

{ID for Printer Driver and its private ) 
{ storage in system resource ) 

{ file) 

{ID for Printer Driver and its private ) 
{ storage ) 


iPStrRFil « $E000; {ID for printer resource file name) 

iPStrPFil ■ $E001; {ID for default spool file name) 


IPrStlDlg - $E000; {ID for style dialog) 

IPrJobDlg - $E001; {ID for job dialog) 


The most important items in a printer resource file are the Printer 
Driver and the printer-specific code* The driver has the standard 
structure for device drivers , as described in the Device Manager 
manual, and implements the Control and Status calls as discussed above 
under "The Printer Driver". 


The printer-specific code is kept in a series of separate overlays. 
They are all of resource type 'PDEF', and their resource IDs are 
available to assembly-language programmers as the following predefined 
constants: 


iPrDraf tID 

.EQU 

0 

;draft printing 

iPrSpoolID 

.EQU 

1 

; spooling 

iPrUserllD 

.EQU 

2 

;printer-specif ic printing, method 1 

!PrUser2ID 

.EQU 

3 

;printer-6pecific printing, method 2 

IPrDlgsID 

.EQU 

4 

;print records and dialogs 

iPrPicID 

.EQU 

5 

; spool printing 


Overlays 0 and 1 do draft printing and spooling, respectively; overlays 
2 and 3, if present, provide additional printing methods for a 
particular printer. All four overlays include the same routines, but 
implement them in different vay6 for the different printing methods. 
When one of the routines is called, the Printing Manager uses the 
bJDocLoop field in the job subrecord to decide which overlay to use. 
Each overlay begins with a list of offsets to the locations of the 
routines within that overlay. 


lOpenDoc 

.EQU 

$000C0000 

;PrOpenDoc 

lCloseDoc 

.EQU 

$00048004 

;PrCloseDoc 

lOpenPage 

.EQU 

$00080008 

;PrOpenPage 

lClosePage 

.EQU 

$0004000C 

;PrClosePage 


This list is followed by the code of the routines themselves. 

Overlay 4 contains the Printing Manager's routines for manipulating 
print records and dialogs: 
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1 Default 

.EQU 

$00048000 

;Print Default 

IStIDialog 

.EQU 

$00048004 

;PrStl Dialog 

lJobDialog 

.EQU 

$00048008 

{PrJobDialog 

1 St Unit 

.EQU 

$00040000 

{PrStllnit 

lJoblnit 

•EQU 

$00040010 

{PrJoblnit 

IDIgMain 

.EQU 

$00048014 

{PrDlgMain 

1 Validate 

• EQU 

$00048018 

{PrValidate 

lJobMerge 

.EQU 

$00088010 

{PrJobMerge 


*** PrStllnit, PrJoblnit, and PrDlgMain are used in customizing the 
dialogs, and will be covered in a later draft of this manual* *** 

Overlays 5 contains just the spool - printing routine PrPicFile (it's 
still preceded by an offset, however): 

IPrPicFile .EQU $00148000 {PrPicFile 
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SUMMARY OF THE PRINTING MANAGER 


Constants 


CONST { Result codes } 


IMeoFullErr “ -108; {not enough heap space} 
noErr ■ 0; {no error} 


{ Printing nethods } 


bDraftLoop ■ 0; {draft printing} 

bSpoolLoop * 1; {spooling} 

bUserlLoop * 2; {printer-specific, method 1} 

bUser2Loop ■ 3; {printer-specific, method 2} 

{ Printer Driver Control call parameters } 


iPrBitsCtl 

IScreenBits 

IPaintBits 

iPrlOCtl 

iPrEvtCtl 

iPrEvtAll 

iPrEvtTop 

iPrDevCtl 

IPrReset 

IPrPageEnd 

IPrLineFeed 

iFMgrCtl 


4; 

{bitMap printing} 

0; 

{configurable} 

l; 

{72 by 72 dots} 

5; 

{text streaming} 

6; 

{screen printing} 

$0002FFFD; 

{print whole screen} 

$0001 FFFD; 

{print top (frontmost) window} 

7; 

{device control} 

$00010000; 

{reset printer} 

$00020000; 

{start new page} 

$00030000; 

{start new line} 

8; 

{used by the Font Manager} 


{ Miscellaneous } 


iPFMaxPgs 

iPrPgFract 

iPrAbort 

iPrRelease 

lPfType 

lPfSig 


128; 

120 ; 

128; 

2 ; 

$5046484C; 

$50535953; 


{maximum number of pages in a spool file} 
{units per inch of paper dimension} 
{result code for halting printing} 
{current version number of Printing } 

{ Manager} 

{spool file type 'PFIL'} 

{spool file creator 'PSYS'} 


{ Printing resources } 


aPrDrvr 

iPrDrvrRef 

IPrintType 

iPrintDef 

iPrintLst 

iPrintDrvr 


'.Print'; 

-3; 

$50524543; 

0 ; 

i; 

2 ; 


{Printer Driver resource name} 
{Printer Driver reference number} 
{type ('PREC') for print records } 
{ and private storage} 

{ID for default print record} 

{ID for previous print record} 

{ID for Printer Driver and its } 

{ private storage in system } 
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IMyPrDrvr - $£000; 


iPStrRFil - $£000 
IPStrPFil - $£001 
IPrStlDlg - $E000 
iPrJobDlg - $E001 


{ resource file} 

(ID for Printer Driver and its } 

{ private storage in printer } 

{ resource file} 

{ID for printer resource file name} 
{ID for default spool file name} 

{ID for style dialog} 

{ID for job dialog} 




Data Types , 

TYPE TPStr80 - “TStr80; 

TStr80 - STRING [80]; 

TPRect - “Rect; 

TPPrPort “ “TPrPort ; 

TPrPort - RECORD 

gPort: Graf Port; {grafPort to draw in} 
gProcs: QDProcs; {pointers to drawing routines} 
{more fields for internal use only} 

END; 


TPPort - PACKED RECORD 

CASE INTEGER OF 

0: (pGPort: GrafPtr); 
1: (pPrPort: TPPrPort) 

END; 


THPrint 

TPPrint 

TPrint 


“TPPrint ; 

“TPrint ; 

RECORD 

IPrVersion: 
prlnfo: 
rPaper : 
prStl: 
prlnfoPT: 
prXInfo: 
pr Job : 
printX: 

END; 


INTEGER; {Printing Manager version} 
TPrlnfo; {printer information} 

Rect; {paper rectangle} 

TPrStl; {style information} 

TPrlnfo; {copy of Prlnfo} 

TPrXInfo; {band information} 

TPrJob; {job information} 

ARRAY [1..19] OF INTEGER 

{used internally} 


TPrlnfo - RECORD 

iDev: INTEGER; {driver information} 
iVRes: INTEGER; {printer vertical resolution} 
iHRes: INTEGER; {printer horizontal resolution} 
rPage : Rect {page rectangle} 

END; 
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TPrStl 


RECORD 

vDev: TWord; 

iPageV: INTEGER; 
IPageH: INTEGER; 
bPort: SignedByte; 
feed : TFeed 

END; 


{u8ed internally} 

{paper height} 

{paper width) 

{printer or modem port} 
{paper type} 


TFeed * (feedCut, {hand-fed, individually cut aheets} 
feedFanfold, {continuous-feed fanfold paper} 
f eedMechCut , {mechanically fed cut sheets} 
feedOther); {other types of paper} 


TPrJob - RECORD 

iFstPage: INTEGER; {first page to print} 
iLstPage: INTEGER; {last page to print} 
iCopies: INTEGER; {number of copies} 

bJDocLoop: SignedByte; {printing method} 
fFromUsr: BOOLEAN; {TRUE if called from application} 
pldleProc: ProcPtr; {background procedure} 
pFileName: TPStr80; {spool file name} 

IFileVol: INTEGER; {volume reference number} 
bFileVers: SignedByte; {version number of spool file} 
bJobX: SignedByte {not used} 

END; 


TPrXInfo - RECORD 

iRowBytes : 
iBandV: 
IBandH: 
iDevBytes: 
i Bands : 
bPat Scale: 
bUl Thick: 
bUlOff set: 
bUl Shadow: 
scan: 
bXInfoX: 


END; 


(scanTB, 

{scan 

scanBT, 

{scan 

scanLR, 

{scan 

scanRL); 

{scan 


INTEGER; 

INTEGER; 

INTEGER; 

INTEGER; 

INTEGER; 

SignedByte ; 

SignedByte; 

SignedByte; 

SignedByte ; 

TScan; 

SignedByte 


{bytes per row} 
{vertical dots} 
{horizontal dots} 
{size of bit image} 
{bands per page} 

{used by QuickDraw} 
{underline thickness} 
{underline offset} 
{underline descender} 
{scan direction} 

{not used} 


top to bottom} 
bottom to top} 
bottom to top} 
right to left} 
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TPrStatus 


RECORD 

iTotPage6 : 
iCurPage : 
iTotCopies : 
i Cur Copy: 
iTotBands : 
iCurBand : 
fPgDirty: 
f Imaging: 
hPrint : 
pPrPort : 
hPic: 

END; 


INTEGER; 

INTEGER; 

INTEGER; 

INTEGER; 

INTEGER; 

INTEGER; 

BOOLEAN; 

BOOLEAN; 

THPrint ; 

TPPrPort ; 

PicHandle 


{total number of pages} 

{page being printed} 

{number of copies} 

{copy being printed} 

{bands per page} 

{band being printed} 

{TRUE if started printing page} 
{TRUE if imaging} 

{print record} 

{printing port} 

{used internally} 




Routines 


Initialization and Termination 

PROCEDURE PrOpen; 

PROCEDURE PrClose; 


Print Records and Dialogs 

PROCEDURE PrintDefault (hPrint: THPrint); 

FUNCTION PrValidate (hPrint: THPrint) : BOOLEAN; 

FUNCTION PrStlDialog (hPrint: THPrint) : BOOLEAN; 

FUNCTION PrJobDialog (hPrint: THPrint) : BOOLEAN; 

PROCEDURE PrJobMerge (hPrintSrc.hPrintDst: THPrint); 


Document Printing 

FUNCTION PrOpenDoc (hPrint: THPrint; pPrPort: TPPrPort; pIOBuf: Ptr) : 

TPPrPort ; 

PROCEDURE PrCloseDoc (pPrPort: TPPrPort); 

PROCEDURE PrOpenPage (pPrPort: TPPrPort; pPageFrame: TPRect); 

PROCEDURE PrClosePage (pPrPort: TPPrPort); 


Spool Printing 

PROCEDURE PrPicFile (hPrint: THPrint; pPrPort: TPPrPort; pIOBuf: Ptr; 

pDevBuf : Ptr; VAR pr Status: TPrStatus); 


Handling Errors [Pascal only ] 

FUNCTION PrError : INTEGER; 

PROCEDURE PrSetError (iErr: INTEGER); 
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Low-Level Driver Access 


PROCEDURE PrDrvrOpen; 

PROCEDURE PrDrvrClose; 

PROCEDURE PrCtlCall (iWhichCtl: INTEGER; lParaml ,lParam2,lParam3: 

Longlnt); 

FUNCTION PrDrvrDCE : Handle; 

FUNCTION PrDrvrVers : INTEGER; 

PROCEDURE PrNoPurge; 

PROCEDURE PrPurge ; 


Resource File Contents 




System Resource File 
Resource 

Name of the current printer 
resource file 

A copy of the device driver for 
the currently installed printer 

A copy of the driver's private 
data storage 


Resource type 
•SIR ' 


'DRVR' 


Resource ID 
-8192 

2 


'PREC 1 
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Printer Resource File 


Resource 

Original copy of the device 
driver for this printer 

Resource type 
'DRVR' 

Resource ID 
-8192 

Original copy of the driver's 
private storage 

•PREC' 

-8192 

Printer-specific code used to 
implement Printing Manager 
routines 

•pdef' 

0 through 6 

Default print record for use 
with this printer 

•PREC' 

0 

Print record from the previous 
printing operation 

•PREC' 

1 

Default spool file name 

•STR ' 

-8191 

Style dialog 

•DLOG' 

-8192 

Job dialog 

•DLOG' 

-8191 

Installation dialog 

’DLOG' 

-8190 

Alert definitions 

•ALRT' 

(private) 

Dialog and alert item lists 

'D1TL' 

(private) 


Assembly-Language Information 


Constants 



; Result codes 

IMemFullErr 

•EQU 

-108 ;not enough heap space 

noErr 

.EQU 

0 ;no error 

; Printing methods 


bDraftLoop 

•EQU 

0 jdraft printing 

bSpoolLoop 

.EQU 

1 ; spooling 

bUserlLoop 

• EQU 

2 jprinter-specific, method 1 

bUser2Loop 

.EQU 

3 jprinter-specific, method 2 


; Printer Driver Control call parameters 
iPrBitsCtl .EQU 4 jbitMap printing 
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IScreenBits 

.EQU 

0 

IPaintBits 

.EQU 

1 

iPrlOCtl 

.EQU 

5 

IPrEvtCtl 

•EQU 

6 

IPrEvtAll 

.EQU 

$00FFFFFD 

iPrEvtTop 

.EQU 

$00FEFFFD 

iPrDevCtl 

.EQU 

7 

IPr Reset 

.EQU 

1 

IPrPageEnd 

.EQU 

2 

IPrLineFeed 

.EQU 

3 

iFMgrCtl 

.EQU 

8 


; Miscellaneous 


iPrintSize 

.EQU 

120 

iPrPortSize 

.EQU 

178 

iPrStatSize 

.EQU 

26 

iPr Abort 

.EQU 

128 

iPr Release 

.EQU 

2 

lPfType 

.EQU 

$5046484C 

lPfSig 

• EQU 

$50535953 


{ Printing 

resources 


iPrDrvrRef 

.EQU 

-3 

IPrintType 

.EQU 

$50524543 

iPrintDef 

.EQU 

0 

IPrintLst 

.EQU 

1 

iPrDrvrID 

.EQU 

2 

IPStrType 

.EQU 

$53545220 

IPStrRFil 

.EQU 

$E000 

iPStrPFil 

.EQU 

$E001 

iPrStlDlg 

.EQU 

$E000 

iPrJobDlg 

.EQU 

$E001 

{ Resource 

IDs for code overlays 

IPrDraftID 

.EQU 

0 

IPr Spool ID 

.EQU 

1 

IPrUserllD 

.EQU 

2 

iPrUser2ID 

.EQU 

3 

IPrDlgsID 

.EQU 

4 

iPrPicID 

.EQU 

5 


configurable 
72 by 72 dots 
text streaming 
;screen printing 
print whole screen 
; print top (frontmost) window 
device control 
reset printer 
start new page 
start new line 
used by the Font Manager 


length of print record 
length of printing port 
length of printer status record 
result code for halting printing 
current version number of Printing 
Manager 

file type (’PFIL*) for spool files 
signature ('PSYS') of Printer program 


Printer Driver reference number 
type ('PREC') for print records 
and private storage 
ID for default print record 
ID for previous print record 
ID for Printer Driver and its 
private storage in system 
resource file 
type 'STR ' for file name 
resources 

ID for printer resource file 
name 

ID for default spool file name 
ID for style dialog 
ID for job dialog 


;draft printing 
{spooling 

{printer-specific printing, method 1 
{printer-specific printing, method 2 
{print records and dialogs 
{spool printing 
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; Offsets to 

document printing code overlays 

lOpenDoc 

•EQU 

$00000000 

;PrOpenDoc 

lCloseDoc 

• EQU 

$00048004 

;PrCloseDoc 

lOpenPage 

• EQU 

$00080008 

;PrOpenPage 

lClosePage 

• EQU 

$0004000C 

;PrClosePage 

; Offsets to 

print record 

and dialog 

code overlays 

IDefault 

• EQU 

$00048000 

;PrintDefault 

lStl Dialog 

•EQU 

$00048004 

{PrStlDialog 

lJobDialog 

• EQU 

$00048008 

;PrJobDialog 

1 St Unit 

•EQU 

$0004000C 

;PrStllnit 

lJoblnit 

• EQU 

$00040010 

;PrJoblnit 

IDIgMain 

•EQU 

$00048014 

;PrDlgMain 

lValidate 

• EQU 

$00048018 

{PrValidate 

lJobMerge 

•EQU 

$00088010 

;PrJobMerge 


; Offset to spool printing code overlay 
IPrPicFile .EQU $00148000 ;PrPicFile 






Printing Port 

gPort GrafPort to draw in 

gProcs Pointers to drawing routines 


Print Record 


IPrVersion 

prlnfo 

rPaper 

prStl 

prJob 


Printing Manager version 
Printer information 
Paper rectangle 
Style information 
Job information 


Printer Information Subrecord 


iDev Driver information 

iVRes Printer vertical resolution 

iHRes Printer horizontal resolution 

rPage Page rectangle 


Style Subrecord 

iPageV Paper height 

iPageH Paper width 

bPort Printer or modem port 

feed Paper type 
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SUMMARY OF THE PRINTING MANAGER 
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Job Subrecord 


IFstPage 
1 Let Page 
1 Copies 
bJDocLoop 
f FromApp 
pldleProc 
pFileName 
iFileVol 
bFileVers 


First page to print 
Last page to print 
Number of copies 
Printing method 

Nonzero if called from application 
Pointer to background procedure 
Spool file name 
Volume reference number 
Version number spool file 


Band Information Subrecord 


IRovBytes 
iBandV 
iBandH 
iDevBytes 
i Bands 
bPat Scale 
bUlThick 
bUlOff set 
bUl Shadow 
scan 


Bytes per row 
Vertical dots 
Horizontal dots 
Size of bit image 
Bands per page 
Used by QuickDraw 
Underline thickness 
Underline offset 
Underline descender 
Scan direction 


Printer Status Record 


iTotPages 

Total number of pages 

1 Cur Page 

Page being printed 

iTotCopies 

Number of copies 

iCurCopy 

Copy being printed 

1 Tot Bands 

Bands per page 

iCurBand 

Band being printed 

fPgDirty 

Nonzero if started printing page 

f Imaging 

Nonzero if imaging 

hPrint 

Print record 

pPrPort 

Printing port 

Variables 



Name Size 

printVars+iPrErr 2 bytes 


Contents 

Current result code 
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GLOSSARY 

background procedure: A procedure passed to the Printing Manager to be 
run during idle times in the printing process* 

band: One of the sections into which a page is divided for imaging and 
printing* 

draft printing: Printing a document by using QuickDraw calls to drive 
the printer's character generator directly* 

imaging: The process of converting an application's description of an 
image (such as a QuickDraw picture) into an actual array of bits to be 
displayed or printed. 

job dialog: A dialog pertaining to one particular printing Job; 
conventionally associated with the application's Print command* 

landscape orientation: The positioning of a document in a printer with 
the long dimension of the paper running horizontally* 

page rectangle: The rectangle marking the boundaries of a printed page 
image. 

paper rectangle: The rectangle marking the boundaries of the physical 
sheet of paper on which a page is printed* 

portrait orientation: The positioning of a document in a printer with 
the long dimension of the paper running vertically. 

Printer: A special application program for printing spool files from a 
disk and configuring different printers* 

Printer Driver: The device driver for the currently installed printer. 

printer resource file: A file containing all the resources needed to 
run the Printing Manager with a particular printer. 

printer status record: A record used by the Printing Manager to report 
on the progress of printing operations* 

printing port: A special grafPort customized for printing instead of 
drawing on the screen. 

print record: A record containing all the information needed by the 
Printing Manager to perform a particular printing Job. 

spool file: A disk file created as the result of spooling. 

spooling: Writing a representation of a document's printed image to a 
disk file, rather than directly to the printer. 
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GLOSSARY A3 


spool printing: Printing the image contained in a spool file. 

style dialog: A dialog pertaining to the use of the printer for a 
particular document; conventionally associated with the application's 
Page Setup command. 
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TO: 


MacPrint Users 


DATE: December 6, 1983 
FROM: Owen Densmore 


SUBJECT: The MacPrint Interface 


Introduction 

Because MacPrint is is not part of the ROM code it must be included with the Application's 
code. Typically this would be done by including the MacPrint code in your Linker job. 

There are two reasons we don't do this. One is that we want to be able to configure 
new printers without re-linking the new print code into the Applications. The other is 
that we cannot assume that all OEM's are using the Lisa Workshop's Linker! Microsoft, 
for example, runs an interpreted "C" environment with a VAX development system! 

Our solution to this packaging problem is to provide four "PDEF" definition procs in a 
special printing resource file. These four def procs break the printing code into four 
disjoint code segments: Dialogs, Spooling, Draft printing, and Picture printing. In addition, 
there is a driver, ".Print", installed in System.rsrc which is accessed like any other driver 
with Open, Close, Status and Control calls. 

A new printer is configured by supplying a new printer resource file, and installing its 
file name [ImageWriter, for example], its ".Print" driver [id=2], and the driver's configuration 
record [PREC, id=2] in System.rsrc. 

Access to these "PDEF" procs is via a very small (374 byte) piece of Print Glue called 
"PrLink" which must be Linked (or some how included!) into your application. In addition, 
the .Print driver can be accessed directly. The driver and its use is discussed in detail 
in a seperate document. 

The Pascal interface is " MacPrint. obj" and the Assembly interface is "PrEqu.text". There 
are four main groups of procedures: Init/Termination, Dialogs, Spooling/Draft, and Picture 
Printing. This release is our "Beta" release. This means that the interface is as stable 
as we can make it. No further procedural interface changes will be made. Only changes 
internal to the code will be allowed. 

Changes 

This is a list of recent changes to printing: 

Added rPaper rectangle to Print record. 

Print record size increased from 80 to 120 bytes. 

Added the PrValidate procedure. 

Made the dialogs configurable by the Application for adding their own buttons. 

Square Pixel cor recti qp. options have been provided for both screen end document 
printing via dialog buttons. 

The default print file name is now included in the Print resource file as a string. 

The .Print Driver (screen printing) now uses a parameter record for configurability. 

We now look for Cmd aborts if a Nil idle proc is used. 

The spooler now provides breaking text into words for screen-HiRes alignment. This 
corrects for minor scaling differences between low and high res. 

Spooling now uses page alligned file buffering. This gives up to 3x speed improvement 
when word breaking! 

Added two new segments to the PrLink interface, both private to printing: 

PrCfgDialog: used to configure the printer from the PrApp program. 

PrHack: a general addition to the interface for stuff we've forgotten! 

Added the procedure PrJobMerge to install the results of a PrJobDialog into several 
documents. This is used as part of Finder printing. 

Added iPrFileVol 3c bPrFileType to the Print record arid the Printer 10 unit. 

And of course lots of bug fixes. 



This release also contains Don's many improvements to the PrApp: 

Installation of new printers via StdFile. __ 

Print file selection using StdFile. ^ 

Icons via bundles. 

Changing of the default print record and screen parameters. 

..and making PrApp a "Real" application. 

Initialization 

The lnit/Termination code consists of: 

PRXEDUf£ PrOpen; 

PROCEDURE PrClose; 

These Open/Close the printing code by opening/closing two files: the current print 
resource file [ImageWriter.rsrc, for example] and the Print driver [.Print] which is 
part of the System, rsrc file. 

PROCEDURE PrintDefault ( hPrint: Tl-Print ); 

This fills a handle to the defaulted Print record from the current print resource file. 

This does not actually dialog. It is used to initialize new "stationary" and to let 
"listing" style applications to get a valid Print record for printing without dialogs. 

The handle must be pre-allocated as 120 bytes. ^ 

FUNCTION PrValidate ( hPrint: THPrint ): Boolean; 

Performs a validity check on the Print record, correcting it if invalid. ' 

Returns True if the record was changed due to being invalid. False otherwise [ie: f Changed}. 
The current validity check is for software version number and for printer type. If either 
are not current, the hPrint record is simply set to the current printer's default values. 

Note: This also updates the information sub-records: Prlnfo, PrXInfo etc according 
to the current values in the PrStl and Pr Job sub-records of the Print record. 

This insures that these "dependent variables" are in synch with their "independent 
variables", the PrStl and PrJob. The returned boolean is not affected if there was 
a change in these values. 

Dialogs 

The Dialogs maintain the primary printing data structure, the "Print" record. Note that 
one of these should be stored in each of your documents so that client use of printing 
can be "remembered". We'll discuss this protocol more later. The dialog procs are: 

FUNCTION PrStlDialog ( hPrint-. THPrint ): Boolean; 

The Mac Applications provide "visual fidelity", i.e. "What you see is what you get". 

This means that you must know something about the printing request before it is actually 
made! The PrStlDialog ^ks for the part of the print request that causes one print job 
to vary from another. For most printers, this is simply the page size and orientation 
for the document. No guarantee is made that this will always be so, however! The 
guarantee is only that enough information is obtained to fill out the part of the Print 
record called the Prlnfo data structure, which will be described further below. 

FUNCTION PrJobDialog f hPrint: THPrint ): Boolean; 

The rest of the Print record is filled out by this dialog. It mainly consists of the 
page range and number of copies. For the Image Writer it also has the HiRes/LoRes/Draft 
choice and the type of paper feed. 

The boolean result for both dialogs is the Dolt button: if true, the Client has clicked "OK". 

The Print record should be saved and, for the PrJob, the document spooled and/or printed. 

Note that the initial button settings are derived from the existing Print record values, and 
should be either an old, valid one, or a new, defaulted one. Each dialog calls PrValidate 
for you. 
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PROCEDURE PrJobMerge (hPrintSrc, hPrintDst: TFPrint); 

"Merges" hPrintSrc's PrJob into hPrintDst [Source/Destination]. Validates both 
records before using them. Updates the associated "Info" records. 

This procedure allows one print job dialog to be applied to several documents. The main 
use is for printing from the Finder. See "Usage" discusson below for details. 

Applications may add their own buttons to the printing dialogs to customize them for their 
own purpose. For example, you could add margins to the PrStlDialog and row/column selection 
to the PrJobDialog. See me for details and samples of how Microsoft is doing it. 

Spooling and Draft Printing 

The Spooling/Draft procs do one of two things: Spool a print file to disk, or provide for an 
Ascii like style of printing. Both are provided by setting up a graf port and intercepting 
QuickDraw calls by using our own versions of the QuickDraw bottleneck procs. Thus these embody 
the minimum use of printing by an App: you can either do "Cheap" ascii printing or spool the file 
to be printed later, "offline", by the Printer Application that will read and print the file. 

The interface is via four procs that "bracket" calls to QuickDraw: 

FUNCTION PrOpenDoc ( hPrint: TFPrint; 

pPrPort: TPPrPort; 

pIOBuf: Ptr ): TPPrPort; 

Initialize the printing code for this document. The hPrint parameter is a handle to a 
valid Print record. The pPrPort is similar to the Window Manager's Storage parameter: if 
Non-NIL, 1 use it, rather than calling NewPtr. The 10 Buffer pointer is passed allong to 
the OS: if NIL, it uses the volume buffer, otherwise it uses yours. The returned pointer 
is to the initialized Print "Port" which is simply a G'raf'Ptr, its associated bottleneck 
procs, and a few extra longs for me. The code will initialize for Draft printing or for 
Pic file spooling by looking at the fDraft flag in the hPrint data If the hPrint has a 
non-NIL IdleProc, it will be called by the draft printing proc. 

PROCEDURE PrCloseDoc ( pPrPort: TPPrPort ) ; 

Puts the above stuff to bed: Flushes the Pic file directories or closes the print driver 
for draft printing. 


PROCEDURE PrOpenPage ( pPrPort: TPPrPort; pPageFrarne: TPRect ); 
Initializes the next page. The page frame rectangle is for wizards: set it to NIL. 

PROCEDURE PrClosePage( pPrPort: TPPrPort ); 

Cleans up the Pic file data structures or ejects the current page. 


Picture & Bitmap Printing 

The Pic printing procs are the standard way to print, 
do simple bitmap printing. 


A third proc is provided to 


PROCEDURE PrPicFile( hPrint : 

pPrPort : 
pIOBuf: 
pDevBuf' : 

VAR PrStatus: 

This reads and prints the spooled print file. 


THPrint; 

TPPrPort ; 

Ptr ; 

Ptr; 

TPrStatus ); 

If an IdleProc is included in the Print 


record, it is run both during imaging and writing to the serial port. The first three 
parameters are identical to the PrOpenDoc parameters. The device buffer is the "band" 
buffer and associated data. If NIL, I allocate it. Its size is Print. PrXInfo.iDevBytes. 

The status record simply records the progress of printing and may be used by the’ IdleProc. 
see PrApp for its use. 
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PROCEDURE PrPic ( 


llPiC : 
hPrint: 
purport : 
pDevBuf : 

VAR PrStatus: 


PicHandle; 
THPrint; 
TPPrPort ; 
Ptr; 

TPrStatus ); 




Simply prints from your picture rather than the spooled file. 


PROCEDURE PrCtlCall (iWhichCtl: Integer; IParamI, lParam2, lParem3: Longlnt); 
is a general control call to the Print driver. In particular: 

PROCEDURE PrCtlCall (. iPrBitsCtl{= 4} --The bitmap printing control 

pBitliap: Ptr; — QuickDraw bitmap 

pPortRect: TPRect; —a portrect. use bounds for whole 
IControl: Longlnt ); — -0=>Screen resolution/Portrait 

..dumps a bitmap to the printer. IControl is a device dep param; use 0 for screen 
printing. Thus PrCtlCall (iPrBitsCtl, ©MyPort^.ScreenBits, ©MyPort^.PortRect.Bounds^) 
performs a screen dump of just my port's data. See the Print Driver memo for more details. 


Usage 

The Printer is initialized by calling the PrOpen procedure. You may either keep the 
printer open all the time, or bracket every print call with a PrOpen/PrClose pair. 

Each document has its own Print record and must store it in the document file. This allows 
the client to configure their documents once rather than each time they open the document. ^ 
To get a vanilla Print record, simply call the PrintDefault procedure. [Note.- Non-document 
printing, listings, for example, may always use defaulting.] 

When an existing document is reopened, the PrValidate procedure must be called. This allows 
the client to change printers with the Printer application and automatically update their 
Print records. 

The two printer dialogs are accessed by menu items. Each returns the Dolt button. The Print 
record should be updated in the document file whenever fDoIt is True. After a PrJobDialog 
is called returning True, the following print loop is generally used: 

pMyPort := PrOpenDoc ( hPrint, phyPort, pIOBuf ); 

FOR iPage :■ 1 TO iPages DO BEGIN { ..or WHILE NOT EOF(myDoc) DO BEGIN } 

PrQpenPage ( pMyPort, NIL ); 

{ Here you image the current page by calling QuickDraw! The drawing proc 
will need the page size and printer resolution stored in the Print .Prlnfo. } 

PrMyPage (iPage, hPrint AA . Prlnfo) ; 

PrClosePage (pMyPorfT; 

END; 

PrCloseDoc (pMyPort); 

This will either spool or draft print the document. If you are printing from your Application 
rather than the Printer Application, you will do the following: 

IF hPrint AA .PrJob.bJDocLoop=bSpoolLoop THEN BEGIN 
SwapMeOut ; 

PrPicFile (....) 

SwapMeln; 

END; 


The "SwapMeOut" procedure swaps as much of you out as reasonable. You may also set flags 



for your GrowZone procedure to let it try to do a last ditch swapout, or at least Alert 
the client that the Printer Application can be used to print the document. PrPicFile 
_ then takes over the machine to print the spooled file. Your "SwapMeln" brings your world 
' back in. 


Printing from the Finder may be done however the App sees fit. The two most obvious 
approaches are: 


-Simply use the doc's current Print record. You should first set the page range and 
number of copies to [1, 999] and 1. This will print the doc exactly as it last printed 
This allows the job mix to include draft,, low res and high res. You should call 
PrValidate before calling the PrPicFile procedure. 

-Put up just one Print Job dialog and apply it to each doc in the queue. This is 
slightly more involved than the above because you want each doc's formatting 
information to be preserved. Here's how to do it: 

Get the first doc's Print record and perform a PrJobDialog with it. 

[Note that you don't have to call PrValidate here because the dialog does 1 

Print it. 

For each additional doc do: 

Get the Print record for this doc. 

Call PrJobMerge. 

Print it. 

The advantage of the first style is that no dialogs occur, thus making is easy for someone to 
submit several documents from different Application for printing. The advantage of the second 
is that it allows one PrJob dialog to be spread over several documents. A third possibility 
is to have the Finder call PrJobDialog with a defaulted Print record and pass it as a parameter 
m the AppParam record. The Apps would then use the second method, possibly with a Print Shop 
proc to move in the job and validate (update) the Print record. 


It is important to stress the use of the Prlnfo sub-record when imaging your document. 
The Prlnfo record contains the device dependent parameters for the current printer. 

If carefully used, it provides the Application with "parametric device independence" 
TPrlnfo = RECORD 

iDev: Integer; {Font mgr /QuickDraw device code} 

iVRes: Integer,: {Resolution of device, in device coordinates} 

iHRes: Integer; { ..note: V before H => compatable with Point.} 

rPage: Reet; {The page (printable) rectangle in device coordinates.} 

END ; 


The most important field is the page rectangle. This gives the current paper size 
in bits. The next is the h/v resolution, in spots per'inch. Finally, there is the 
QuickDraw - FontMgr device number. This lets you get the metrics for the printing 
fonts, so that you can adjust for screen-printer differences. Correct use of these 
will result in a very surprising degree of printer independence. 


In addition Prlnfo, there is another field in the Print record: rPaper: Rect which 
gives the paper rectangle in which the Prlnfo. rPage is embedded, in device coordinates 
This is Outset' from the rPage rectangle, whch always has 0,0 top left coordinates. 
Its use is for margin calculations. 


The Print record contains an IdleProc pointer that is set to Nil by the PrJobDialog. By changin 
this to your own procedure, you may simulate multi-processing! For example, you can look at 
either PrTest or PrApp to see how you may run the ornaments while printing.’ if you don't provid 
an IdleProc, we provide a simple Comand Period abort procedure: you should post an alert/di alng 
informing the client that this is available. 


•spooling may be to files other than the default spool file (whose name is configurable by the 
client,!. The file name is provided as a string pointer in the Print record. It is set to 
Nil by the PrJobDialog. This causes spooling to the default file name. Simply provide 
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your own file name if you'd like to. This is especially useful for Applications that cannot 
print from within themselves. The volume/version parameters are similarly changable. 

Motes 

Errors: The Alert (ha) reader will have noticed a lack of error returns from printing. Wher 

we can issue our own Alerts, we do so. Other errors are handled by posting the 
error in the printer globals. The first integer is the current error number. 

In case the user's disk does not have a printing resource file, or it is incorrectly 
named in System. rsrc, or there is no .Print driver; we simply post an error and 
No-op in the PrLink code. We do not alert from PrLink. 


Size: 


Printing is really a Mini-Application rather than a library. The code is currently 
roughly 8K. But this is really a small part of the cost of printing; even ifthe 
code were "free", the data used by printing can be huge. 


Current sizes [10/6]: 


Code: 


780 
= 374 
= 2,226 
= 1,294 
= 2,134 
= 4,630 

= 6K for HiRes 

= 5K to 15K, typically. Max = 32K 
= 3K to 1QK, typically. Max = 32K 
= 2K to 6K, typically; up to 12K for 24 Pt shadow HiRe 
This is why a separate Printer Application is provided: you may simply spool and let 
the client use it. For spread sheets, for example. Draft printing may be adequate 
for most uses. 


Data: 


.Print Driver 

PrLink 

Dialogs 

Spooling 

Draft 

Pic Printing 
Bands 
Picture 
Fonts 

QuickDraw Buf 




Bands: The size or" a HiRes page bitmap is in the order of 1/4 Megabyte! Printing handles 

this by breaking the page into smaller "bands" and alternates imaging and print i *■ 

to print a page. For example, a HiRes US Letter size page has 47 bands of 5120 byte 
for a total of 240,640 bytes. LoRes is 24 bands of 2560 bytes for a total of 61,440 
[Note: as resolution doubles, data volune quadruples!] Please note that even though 
may appear gargantuan, the printer uses far less than the screen's 20K! 


Spooling.- Even if you plan to try to print from within the App, spooling is useful! It allows 
you to have a very clean swapping stratagy: First you spool, with only 3K of printi 
code and no more than IK data. This may require much of your code and data to t re 
But when the data is spooled, you can swap all of your code and data out and cal- 
PrPicFile from its own micro segment! The banding stratagy requires very fast imagi 
- of the data if it is to be drawn 50 times per page. This is another reason for spoo 
Pic drawing is optimal use of QuickDraw! Generally spooling is done to the default 
Print File whose name is stored the Print .rsrc file for the translators to change. 
You may over-*rde this by setting three fields in the Print record-. 

pFileName: TPStrSO; [Spool File Name: NIL for default.} 

iFileVol: Integer; [Spool File vol, set to 0 initially} 

bFileVers: SignedByte; [Spool File version, set to 0 initially} 

These are set to NIL, 0, 0 by the Print Job dialog. Change them if you'd like. 


Draft: Draft printing is a compromise between Ascii/WriteLn/Fast printing and QuickDraw. 

One of the strongest Mac attitudes is the full use of the QuickDraw style of imaging 
Note that there are NO WriteLn's available for Mac programmers, and NO programs use 
command line interface! I decided that the best compromise was Draft printing. It 
called "Draft" mainly because it "simulates" the output you will get when you print 
with standard printing. It is done by simply installing QuickDraw capture procs and 
translating them to the printer's command codes. It thus can provide full use of th 
printer's native capabilities, such as bold, underline, fonts, line plotting, et 
It also requires no special interface such as WriteLn; thus the standard Apps ge it 
without even being aware its happening! ..Its completely under client control! 
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"But what do I do if all I want to do is make a Listing?!" Well, its really not so 
bad: simply get a default Print record, and make your own WriteLn! The only real 
headache is having to be aware of the Page boundaries. But the advantage is that 
^ the results will nicely fit European paper sizes, and you'll probably find that 

"Pretty Printing" will be so easy that you'll provide it. Note that it also 
lets you provide Spooled standard printing by simply changing one flag! 

Idle: The Print record has a IdleProc: Print .PrJob.pIdleProc. It is always returned NIL b 

the default and dialog procs. To use it, simply stuff it with your own proc after t 
PrJobDialog and before calling the Draft or Pic Printing procs. A word of caution, 
however! The "concurrency" problems caused by the Idle proc are subtle and many! 
Look at the PrTest and PrApp samples for how they do it. The major problem is makin 
sure the GrafPort is reset to mine when returning from your idle. Also, DON'T allow 
calling Printing procs while idling. They are accessed through the PrLink code whic 
is not re-entrant. The suggested idle proc is one polling for Cmd "." aborts. To a 
printing, simply put iPrAbort into iPrErr in the PrintVars in low memory. 

Release: Billions of files are released on the MacPrint disk, only four of which you need: 

PrLink to Link with, either MacPrint. obj or PrEqu.text to cornpile/assemble with, 
the current print resource to run with, and PrApp to let your client print spooled 
files with. New releases of printing simply use a new print resource, even if addin 
a new printer! Note however, that you must have the newest System. rsrc file which 
contains two vital printing resources: the .Print driver arid a string containing the 
file name of the current printing resource [=ImageWriter] . If you have an older 
System. rsrc, it can be updated with these, using Clover, by pasting the small file 
PrSys.rsrc included in the printing release into System. rsrc. 
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TO: MacPrint Users 

SUBJECT: The .Print Driver 


DATE: December 7, 1983 
FROM: Owen Densmore 


Introduction 

The MacPrint system is packaged as three separate items.- 

-Three entries in System.rsrc, the .Print driver being the major one, 

-The Printer resource file, currently "ImageWriter", 

-The Printer Application program, "Printer". 

The three entries in the System.rsrc file are: 

-The .Print driver [ResType-DRVR, ReslD-2, ResNeme-". Print", RefNum-$FFFD], 

-A parameter record used to configure the .Print driver[ResType=PREC, ResID=2]. 

-A string naming the current printer [ResType=STRG, ResID=$EOOO(-8192)], 

The System.rsrc string is used to locate the "current" printer, and allows the translators 
to name the printer appropriately for the target country. This allows several printers 
to be available at once, but with only one being active. The installation of a new 
printer (or renaming of the existing one) is done by installation dialogs in the Printer 
application program. Thus I may change my ImageWriter's name to "StarChild" by simply 
editing its name in the Finder and using the Printer application to install it. 

The .Print driver and its associated parameter record reside both in System.rsrc awrfin the 
printer resource file. This redundancy is necessary for the installation scheme discussed 
above. We require a place in System.rsrc so that the system itself can use the current printer 
for screen printing. It also allows applications not using the complete printing system to 
do bitmap-only printing easily. The copies in the printer resource are never executed; 
they are simply used as a storage area for installing into System.rsrc. 

This document discusses the use of the Printer driver. The printer resource is documented 
in the "MacPrint Interface" specification memo. 

Driver Calls 

The driver contains the following general calls-. 

Status: Returns the Font Manager's device information record. 

Controls: 

Control 4 = Bitmap Printing, 

Control 5 * Block 10 to printer. 

Control 6 * Keyboard event controls. 

Control 8 = Font (Manager's font selection over-ride option. 

The Bitmap Printing control (4) uses three long parameters for printing a portion 
of a bitmap: 

CSParam = pointer to QuickDraw bitmap, 

CSParam+4 = pointer to rectangle within bitmap, in local coordinates, 

CSParera+8 = a device dependent parameter; use 6 for screen printing. 

Thus to print the entire screen: --or— the contents of a window-. 

CSParam = screenBits, CSParam = window. portBits, 

CSParam+4 = screenBits. bounds, CSParam+4 = window.portRect, 

CSParam+8 = 0. CSParam+8 = 0. 

The Block 10 control (5) uses three long parameters for writing a block of raw data 

to the printer. It's primarily useful for ascii printing, form feeds, cr's etc 

and for use by the higher level printing code for sending escape commands to the printer. 

The parameters are: 



CSParam = pointer to block, 

CSParam+4 = a long count of bytes, 

CSParam+8 = a pointer to an Idle procedure; use NIL for none. 

The Print Event control (6) uses one long parameter for handling two special cases 
of Bitmap printing. The parameter's format is: 

CSParam * Event "Message"; which is formatted as follows: 

Byte 3=0, 

Byte 2=$FF for printing screen, $FE for printing just the top folder. 
Bytes 1 & 2=$FFFD,.the driver's RefNum. 

Thus $OOFFFFFD is the screen dump message, while $OOFEFFFD is the top folder message. 

The Font Manager control (8) is the "tail hook" that is called by the Font Manager 
after it responds to a QuickDraw request for a new font. It allows a device to 
over-ride the Font Manager's selection heuristic. 

The following constants are in our "Printing Equates" file, "PrEqu.text": 


; These are 

the PrDrvr 

constants. 


iPrDrvrID 

.EQU 

2 

;Driver‘s ResID 

iPrDrvrRef 

.EOU 

$FFFD 

;Driver's RefNuri = NOT ResID 

iPrBitsCtl 

.EQU 

4 

; The Bitmap Print Proc's ctl number ^ 

iPrlOCtl 

.EQU 

5 

; The Raw Byte 10 Proc's ctl number 

iPrEvtCtl 

.EQU 

6 

;The PrEvent Proc's ctl number 

IPrEvtAll 

.EQU 

$00FFFFFD 

; The PrEvent Proc's CParam for the screen 

IPrEvtTop 

.EQU 

SOOFEFFFD 

; The PrEvent Proc's CParam for the top folder 

iFMgrCtl 

.EQU 

8 

;The FMgr's Tail-hook 


..there are similar definitions in the MacPrint Pascal interface. 

Unit PrScreen, a simple Driver interface 

The unit PrScreen [<100 bytes!] contains a very simple Pascal interface to .Print. 
The interface definition is included in MacPrint. You may also simply declare these 
as Externa] references if you'd rather not {$Use MacPrint}. 

PROCEDURE PrDrvrOpen; 

PROCEDURE PrDrvrClose; 

PROCEDURE PrCtlCall (iWhichCtl: Integer; IParamI, lParam2, lParam3: Longlnt); 

The first two simply open & close the driver in System.rsrc. Be careful not to 
close the driver if someone else has opened it before you got there! 

The third is simply a generalized control call to the driver. It takes a control 
call number, and up to three parameters. Thus the above controls are accessed by: 

PrCtlCall (iPrBitsCtl, pBitMap, pPortRect, lControl); 

PrCtlCall (iPrEvtCtl, IPrEvtAll, 0, 0); 

-PrCtlCall (iPrEvtCtl, IPrEvtTop, 0, 0); 

PrCtlCall (iPrlOCtl, pBuf, lBufCount, pldleProc); 

These constants are also declared in MacPrint: 

iPrBitsCtl = 4; {The Bitmap Print Proc's ctl number} 

iPrlOCtl = 5; {The Raw Byte 10 Proc's ctl number} 

iPrEvtCtl = 6; {The PrEvent Proc's ctl number} 

IPrEvtAll = $0002FFFD; {The PrEvent Proc's CParam for the entire screen} 
IPrEvtTop = $0001 FFFD; {The PrEvent Proc's CParam for the top folder} 
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ABOUT THIS MANUAL 

This manual introduces you to the "inside" of Macintoshs the Operating 
System, the User Interface Toolbox, and other routines that your 
application program may call* It will help you figure out which 
software you need to learn more about and how to proceed with the rest 
of the technical documentation* *** Eventually it will be an 
introductory chapter in a comprehensive manual that describes 
everything in detail* *** 

You should already be familiar with the Macintosh User Interface 
Guidelines. All Macintosh programmers should follow these guidelines 
to ensure that the end user is presented with a consistent interface* 

It would also be helpful for you to be familiar with an existing 
Macintosh application* 

This manual begins with a general overview of the software your 
application program will use, followed by individual overviews of the 
User Interface Toolbox and the Operating System. Following these 
overviews is a section that tells you how to proceed with reading the 
rest of the Toolbox and Operating System documentation* Finally, 
there's a glossary of terms used in this manual* 


GENERAL OVERVIEW 


The routines available for use in Macintosh application programs are 
divided into functional units, many of which are called "managers" of 
the application feature that they support. As shown in Figure 1 on the 
following page, most units are part of either the Operating System or 
the User Interface Toolbox and are in the Macintosh ROM* 

The Operating System is at the lowest level; it does basic tasks such 
as interrupt handling, memory management, and I/O* The User Interface 
Toolbox is a level above the Operating System; it exists to help you 
implement the standard Macintosh user interface in your application* 

The Toolbox calls the Operating System when necessary to do low-level 
operations, and you'll also call the Operating System directly 
yourself* 

Other software is available for performing specialized operations that 
aren't integral to the user interface but may be useful to some 
applications. This includes routines for doing printing and 
floating-point arithmetic. Such software isn't located in the 
Macintosh ROM, nor are certain special-purpose Toolbox units (such as 
CoreEdit, for doing sophisticated text editing). The entire Operating 
System and all the commonly used Toolbox units are in ROM. 
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A MACINTOSH APPLICATION PROGRAM 


THE USER INTERFACE TOOLBOX 

The Resource Manager 

QuickDraw 

The Font Manager 

The Toolbox Event Manager 

The Window Manager 

The Control Manager 

The Menu Manager 

TextEdit 

CoreEdit (not in ROM) 

The Dialog Manager 
The Desk Manager 
The Scrap Manager 
The Toolbox Utilities 
The System Error Handler 
The Package Manager 


OTHER HIGH-LEVEL SOFTWARE 
(not in ROM) 

Printing 

Floating-Point Arithmetic Package 
Transcendental Functions Package 
Standard File Package 
International Utilities Package 


THE OPERATING SYSTEM 

The Memory Manager 
The Segment Loader 
The OS Event Manager 
The Keyboard/ Mouse Handler 
The File Manager 
The Device Manager 
The Disk Driver 
The Sound Driver 
The Serial Driver 
The Vertical Fie trace Manager 
The OS Core (Trap Dispatcher, 
interrupt handlers, etc.) 

The OS Utilities 


OTHER LOW-LEVEL SOFTWARE 
(not in ROM) 

Disk Formatting Package 


THE MACINTOSH HARDWARE 


Figure 1. Overview 
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GENERAL OVERVIEW 5 


Macintosh applications can be written most easily in Pascal, since all 
units have a Pascal interface *** or will eventually ***. For greater 
efficiency, however, you may want to use assembly language or a 
combination of Pascal and assembly language. *** Currently you must 
develop your application on a Lisa computer and convert it to a 
Macintosh disk before trying it out. Eventually development will be 
possible on the Macintosh itself* *** 


ABOUT THE USER INTERFACE TOOLBOX 






The Macintosh User Interface Toolbox provides a simple means of 
constructing application programs that conform to the Macintosh User 
Interface Guidelines. By offering a common set of routines that every 
application calls to implement the user interface, the Toolbox not only 
ensures consistency but also helps reduce the application's code size 
and development time. At the same time, it allows a great deal of 
flexibility: an application can use its own code instead of a Toolbox 
call wherever appropriate, and can define its own types of windows, 
menus, controls, and desk accessories. 


Figure 2 shows the Toolbox units in rough order of their level, from 
the lowest level at the bottom to the highest level at the top. There 
are many interconnections between these units; the lower-level ones are 
in many cases called by those at the higher levels. 


Desk Manager 


Scrap Manager 


Dialog Manager 


Control Manager 


Menu Manager 


TextEdit 


CoreEdit (not in ROM) 


Window Manager 
Toolbox Utilities 


QuickDraw 


Toolbox Event Manager 


Font Manager 
Resource Manager 


(To be added: 

System Error Handier 
and Package Manager) 


Figure 2. Toolbox Units 


To keep the data of an application separate from its code, making the 
data easier to modify and easier to share among applications, the 
Toolbox includes the Resource Manager . The Resource Manager lets you, 
for example, store menus separately from your code so that they can be 
edited or translated without requiring recompilation of the code. It 
also allows you to get standard data, such as the wristwatch graphic 
that means "wait", from a shared system file. When you call other 
Toolbox units that need access to the data, they call the Resource 
Manager. Although most applications never need to call the Resource 
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Manager directly, an understanding of the concepts behind it is 
essential* 

Graphics are an important part of every Macintosh application* All 
graphic operations on the Macintosh are performed by the QuickDraw 
unit. To draw something on the screen, you’ll often call one of the 
other Toolbox units, but that unit will in turn call QuickDraw. You'll 
also call QuickDraw directly, usually to draw inside a window. 
QuickDraw's underlying concepts, like those of the Resource Manager, 
are important for you to understand. 

Graphics include text as well as pictures. To draw. text, QuickDraw 
calls the Font Manager » which does the background work necessary to 
make a variety of character fonts available in various sizes and 
styles. Unless an application includes a font menu, it usually need 
not be concerned with the Font Manager. 

An application decides what to do from moment to moment by examining 
input from the user, in the form of mouse and keyboard actions. It 
learns of such actions by repeatedly calling the Toolbox Event Manager 
(which in turn calls another, lower-level Event Manager in the 
Operating System). The Toolbox Event Manager also reports occurrences 
within the application that may require a response, such as when a 
window that was overlapped becomes exposed and needs to be redrawn. 

All information presented by a standard Macintosh application appears 
in windows. To create windows, activate them, move them, resize them, 
or close them, you'll call the Window Manager. It keeps track of 
overlapping windows, so you can manipulate windows without concern for 
how they overlap. The Window Manager, for example, tells the Toolbox 
Event Manager when to inform your application that a window has to be 
redrawn. Also, when the user presses the mouse button, you call the 
Window Manager to learn which part of which window it was pressed in, 
if any, or whether it was pressed in the menu bar or a desk accessory. 

Any window may contain controls, such as buttons, check boxes, and 
scroll bars. You create and manipulate controls with the Control 
Manager . When you learn from the Window Manager that the user pressed 
the mouse button inside a window containing controls, you call the 
Control Manager to find out which control it was pressed in, if any. 

A common place for the user to press the mouse button is, of course, in 
the menu bar. You set up menus in the menu bar by calling the Menu 
Manager . When the user gives a command, either from a menu with the 
mouse or from the keyboard with the Command key, you call the Menu 
Manager to find out which command was given. 

To accept text typed by the user and allow the standard editing 
capabilities, such as cutting and pasting within a document via the 
Clipboard, your application can call either TextEdit or CoreEdit . 
TextEdit is especially easy to use but doesn't support advanced editing 
and formatting features such as fully justified text, tabbing, or 
recognition of word boundaries during cutting and pasting; for these, 
you'll have to use CoreEdit. Bear in mind, however, that CoreEdit is 
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not in the Macintosh ROM; instead, it occupies over 6K of your 
application's available memory. 

When an application needs more information from the user about a 
command, it presents a dialog box. In case of errors or potentially 
dangerous situations, it gives the user an alert, in the form of an 
alert box or sound from the Macintosh's speaker (or both). To create 
and present dialogs and alerts, and find out the user's responses to 
them, you call the Dialog Manager . 

Every Macintosh application should support the use of desk accessories. 
The user opens desk accessories through the Apple menu, which you set 
up by calling the Menu Manager. When you learn that the user has 
pressed the mouse button in a desk accessory, you pass that information 
on to the accessory by calling the Desk Manager . The Desk Manager also 
includes routines that you must call to ensure that desk accessories 
behave properly. 

As mentioned above, you can use TextEdit or CoreEdit to implement the 
standard text editing capability of cutting and pasting via the 
Clipboard in your application. However, to extend the use of the 
Clipboard to allow cutting and pasting between your application and 
another application or a desk accessory, you need to call the Scrap 
Manager . 

Finally, some generally useful operations such as fixed-point 
arithmetic, string manipulation, and logical operations on bits may be 
performed with the Toolbox Utilities . 

*** To be added: System Error Handler, Package Manager, and other 
high-level software *** 


ABOUT THE OPERATING SYSTEM 


The Macintosh Operating System provides the low-level support that 
applications need in order to use the Macintosh hardware. As the 
Toolbox is your program's interface to the user, the Operating System 
is its interface to the Macintosh. 

The Memory Manager dynamically allocates and releases memory for use by 
applications and by the other parts of the Operating System. Most of 
the memory that your program uses is in an area called the heap ; the 
code of the program itself occupies space in the heap. Memory space in 
the heap must be obtained from the Memory Manager. 

The Segment Loader is the part of the Operating System that loads the 
program code into memory to be executed. Your program can be loaded 
all at once as a single unit, or you can divide it up into dynamically 
loaded segments to economize on memory usage. 

Low-level, hardware-related events such as mouse-button presses and 
keystrokes are reported by the Operating System Event Manager . (The 
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Toolbox Event Manager then passes them along to the application, along 
with higher-level, software-generated events added at the Toolbox 
level.) The Operating System Event Manager learns of mouse and 
keyboard actions in particular from the Keyboard /Mouse Handier • Your 
program will ordinarily deal only with the Toolbox Event Manager and 
rarely call the Operating System Event Manager or the Keyboard/Mouse 
Handler directly. 

File I/O is supported by the File Manager , and device I/O by the Device 
Manager. The task of making the various types of devices present the 
same interface to the application is performed by specialized device 
drivers. The Operating System includes three built-in drivers: 

- The Disk Driver controls data storage and retrieval on 400K-byte 
3 1 /2-inch disks. 

- The Sound Driver controls sound generation, including music 
composed of four simultaneous tones. 

- The Serial Driver reads and writes asynchronous data through the 
two serial ports, providing communication between applications and 
serial peripheral devices such as a modem or printer. 

Other drivers can be added independently or built on the existing 
drivers. For example, a printer driver can be built on the Serial 
Driver or a music driver built on the Sound Driver. 

The Macintosh video circuitry generates a vertical retrace interrupt 
(also known as the vertical blanking or VBL interrupt) sixty times a 
second while the beam of the display tube returns from the bottom of 
the screen to the top to display the next frame. The system uses this 
interrupt as a convenient time to perform recurrent tasks such as 
checking the state of the mouse button. An application can also 
schedule routines to be executed at regular intervals based on this 
"heartbeat" of the system. The Vertical Retrace Manager handles the 
scheduling and execution of tasks during the vertical retrace 
interrupt. 

At the very lowest level is the Operating System Core , which does the 
actual interrupt handling, initialization, and other important 
background work necessary to keep the Macintosh functioning. Via the 
Trap Dispatcher , it provides the connection between your request for a 
Toolbox or Operating System service and the physical code that performs 
that service. 

Finally, there are miscellaneous Operating System Utilities for doing 
such things as setting the date and time or finding out the user f s 
preferred speaker volume. 

*** To be added: other low-level software (Disk Formatting Package) 
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WHERE TO GO FROM HERE 


*** This section will be considerably rewritten for the final 
comprehensive manual. *** 

The technical documentation will eventually be ordered in such a way 
that you can follow it if you read it sequentially. The proposed order 
for the documentation that's already written is given below. Before 
you begin, you should be familiar with Lisa Pascal, as described in the 
Pascal Reference Manual for the Lisa . You should also know a little 
bit about the Macintosh's memory management— heaps , handles, and the 
like. For now you can read about these in the Memory Manager manual, 
from "About the Memory Manager" through "Utility Data Types"; 
eventually there will be a separate overview of memory management. 

The Resource Manager: A Programmer's Guide 
QuickDraw: A Programmer's Guide 
The Font Manager: A Programmer's Guide 
The Event Manager: A Programmer's Guide 
The Window Manager: A Programmer's Guide 
Macintosh Control Manager Programmer's Guide 
The Menu Manager: A Programmer's Guide 
TextEdit: A Programmer's Guide 
CoreEdit: A Programmer's Guide 
The Dialog Manager: A Programmer's Guide 
The Desk Manager: A Programmer's Guide 
The Scrap Manager: A Programmer's Guide 
The Toolbox Utilities: A Programmer's Guide 
The Memory Manager: A Programmer's Guide 
Macintosh Operating System Reference Manual 
The Segment Loader: A Programmer's Guide 
Putting Together a Macintosh Application 


(hand) 

The Macintosh Operating System Reference Manual is very 
out-of-date, incomplete, and in a different format from 
the other manuals. It will eventually be completely 
replaced by up-to-date documentation in the usual format. 


(hand) 

Anything not listed above hasn't been documented yet by 
Macintosh User Education, although programmer's notes or 
other preliminary documentation may be available. Check 
with Macintosh Technical Support. 

The individual manuals identify any special-purpose information that 
can possibly be skipped. Most likely you won't need to read everything 
in each manual and can even skip entire manuals. You should at least 
read the manuals on the Toolbox units that deal with the fundamental 
aspects of the user interface: the Resource Manager, QuickDraw, the 
Toolbox Event Manager, the Window Manager, and the Menu Manager. Read 
the other manuals if you're interested in what they discuss, which you 
should be able to tell from the above overviews and from the 
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introductions to the manuals themselves. Each manual's introduction 
will also tell you what you should already know before reading that 
manual • 

The documentation is oriented toward Pascal programmers. If you want 
to program in assembly language, read the "Using QuickDraw from 
Assembly Language" section of the QuickDraw manual. (Eventually that 
section will be removed and there will be a separate, more detailed 
discussion of using assembly language.) There are also notes for 
assembly-language programmers throughout every manual. 

Read the manual "Putting Together a Macintosh Application" when you're 
ready to try something out. Currently the documentation doesn't 
include any sample programs, but you can get some through Macintosh 
Technical Support in the meantime. 
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GLOSSARY 


Control Manager: A Toolbox unit that provides routines for creating 
and manipulating controls (such as buttons , check boxes , and scroll 
bars)* 

CoreEdit: A Toolbox unit that handles sophisticated text editing and 
formatting, including fully justified text, tabbing, and recognition of 
word boundaries during cutting and pasting* 

Desk Manager: A Toolbox unit that supports the use of desk accessories 
from an application* 

device driver: A piece of Operating System software that controls a 
peripheral device and makes it present the standard interface to the 
application* 

Device Manager: The part of the Operating System that supports device 
I/O. 

Dialog Manager: A Toolbox unit that provides routines for implementing 
dialogs and alerts* 

Disk Driver: The device driver that controls data storage and 
retrieval on 400K-byte 3 1 /2-inch disks* 

Event Manager: See Toolbox Event Manager or Operating System Event 
Manager* 

File Manager: The part of the Operating System that supports file I/O* 

Font Manager: A Toolbox unit that supports the use of various 
character fonts for QuickDraw when it draws text* 

heap: An area of memory in which space can be allocated and released 
on demand, using the Memory Manager* 

Keyboard /Mouse Handler: The part of the Operating System that controls 
communication with the keyboard and the mouse* 

Memory Manager: The part of the Operating System that dynamically 
allocates and releases memory space in the heap* 

Menu Manager: A Toolbox unit that deals with setting up menus and 
letting the user choose from them* 

Operating System: The lowest-level software in the Macintosh* It does 
basic tasks such as interrupt handling, memory management, and I/O* 

Operating System Core: The part of the Operating System that does the 
actual interrupt handling, initialization, and other important 
background work necessary to keep the Macintosh functioning* 


12/22/83 Rose 


CONFIDENTIAL 


/ROAD.MAP/ROAD.G 



12 


Inside Macintosh Road Map 


Operating System Event Manager: The part of the Operating System that 
reports hardware "related events such as mouse-button presses and 
keystrokes* 

Operating System Utilities: Operating System routines that perform 
miscellaneous tasks such as setting the date and time or finding out 
the user's preferred speaker volume. 

QuickDraw: The Toolbox unit that performs all graphic operations on 
the Macintosh screen. 

resource: Data used by an application (such as menus , fonts* and 
icons)* and also the application code itself. 

Resource Manager: The Toolbox unit that reads and writes resources. 

Scrap Manager: The Toolbox unit that enables cutting and pasting 
between applications* desk accessories, or an application and a desk 
accessory. 

Segment Loader: The part of the Operating System that loads the code 
of an application into memory, either as a single unit or divided into 
dynamically loaded segments. 

Serial Driver: The device driver that controls communication, via 
serial ports, between applications and serial peripheral devices. 

Sound Driver: The device driver that controls sound generation in an 
application. 

TextEdit: A Toolbox unit that supports the basic text entry and 
editing capabilities of a standard Macintosh application. 

Toolbox: Same as User Interface Toolbox. 

Toolbox Event Manager: A Toolbox unit that allows your application 
program to monitor the user's actions with the mouse, keyboard, and 
keypad • 

Toolbox Utilities: A Toolbox unit that performs generally useful 
operations such as fixed— point arithmetic, string manipulation, and 
logical operations on bits. 

Trap Dispatcher: The part of the Operating System Core that provides 
the connection between your request for a Toolbox or Operating System 
service and the physical code that performs that service. 

User Interface Toolbox: A set of routines and data types that help you 
implement the standard Macintosh user interface in your application. 

vertical retrace interrupt: An interrupt generated sixty times a 
second by the Macintosh video circuitry while the beam of the display 
tube returns from the bottom of the screen to the top; also known as 
the vertical blanking or VBL interrupt. 
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Vertical Retrace Manager: The part of the Operating System that 
schedules and executes tasks during the vertical retrace interrupt. 

Window Manager: A Toolbox unit that provides routines for creating and 
manipulating windows. 
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COMMENTS? 

Macintosh User Education encourages your comments on this manual. 

- What do you like or dislike about it? 

- Were you able to find the information you needed? 

- Was it complete and accurate? 

- Do you have any suggestions for improvement? 

Please send your comments to the author (indicated on the cover 
page) at 10460 Bandley Drive M/S 3-Q, Cupertino CA 95014. 

Mark up a copy of the manual or note your remarks separately. 

(Well return your marked-up copy if you like.) 


Thanks for your helpl 
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Modification History: First Draft (ROM 4.4) C. Rose 8/8/83 
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ABSTRACT 

This manual introduces you to the "inside" of Macintosh: the Operating 
System and other routines that your Macintosh application program will 
call. It will help you figure out which software you need to learn more 
about and how to proceed with the rest of the technical documentation. 


Summary of significant changes and additions since last version: 

- The Toolbox overview has been rewritten, and the Operating System 
overview has been added. 

- "About Using Assembly Language" has been removed; it will be 
replaced by other documentation. 

- "Where to Go From Here" has been updated. 
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SUMMARY OF FP68K DOCUMENTS 
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User's Guide — — an overview of FP68K ELEMS68K and Cheir design philosophy* 

Programmer's Guide — hints on how to build the packages, and 
how to modify them, if necessary; details about system 
dependencies involving the state area* Includes register^ 
map templates* 

System Interface — how FP68K and ELEMS68K affect their execution environment. 

High-Level Interface — the SANE Pascal unit and assembly macros. 

Integer Conversion Tests 

Binary-Decimal Conversion Tests 

IEEE Tests — a set of test vectors designed for this style of 
arithmetic and distributed through the standards 
subcommittee 

Binary-Decimal Conversions — what is available through the SANE 
interface, and what FP68K provides at the low level. 

A sample parser and formatter from the SANE interface 
is shown. 

P75A stuff — papers related to the arithmetic standard. 


1 November 83 


Jerome T. Coonen 



SUMMARY OF FP68K FILES 


FPxxx.TEXT — source files for FP68K, except for binary-decimal 
conversions 

FBxxx.TEXT — source files for binary-decimal part of FP68K 

SAxxx . TEXT — SANE68 . TEXT — SANE interface section 

SAIMP68 .TEXT — SANE implementation section 

SAASM68.TEXT — • SANE assembly procedures 

SAMAC68.TEXT — EQU's and MACRO'S for assembly interface 

DOxxx.TEXT — documentation using SCRIPT formatter, with 
macros in DODRIVER. TEXT 

TVxxx.TEXT — IEEE test vector files, required operations 
TWxxx.TEXT — IEEE test vector files, appendix funtions 
TDxxx.TEXT — Test vector driver program files 
ITxxx.TEXT — integer < — > extended conversion tests 
IOxxx.TEXT — binary < — > decimal conversions tests 
Zyyyy.OBJ — executable test programs 

ELxxx.TEXT — elementary transcendental and financial functions 


4 
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Introduction 

The 68000 software floating-point packages, FP68K and ELEMS68K, appear 
much like simple subroutines but their interaction with the host system is 
somewhat more subtle. This document indicates possible trouble spots. It is 
intended for system implementors, rather than users of FP68K and ELEMS68K. 

The following sections describe the various issues in turn. 


Registers and stack used 

FP68K and ELEMS68K receive all of their parameters on the stack. They 
save and restore all of the CPU registers across calls, except that DO is 
modified by the REMAINDER operation. FP68K modifies the CPU Condition Code 
Register as described later. 

As detailed in the "Program Notes" document, FP68K typically uses up to 
41 words of stack beyond the input parameters. The only exceptions are the 
binary-decimal conversion and nextafter routines, which may use up to 120 
words beyond the input parameters. ELEMS68K uses at most 30 words of stack 
for temporary storage. 


Single entry point 

FP68K has just one entry point — with the label 'FP68K'. When invoked, 
FP68K expects the return address on the stack, followed by a one-word opcode 
described in the user's guide. Beyond the opcode are up to three operand 
addresses (depending on the operation). Note that because the operands are 
passed by address, they must be in memory, NOT IN THE REGISTER FILE. 

If FP68K is to be invoked by a mechanism like the A-line trap, care must 
be taken that stack is set up properly. Depending on the system, it should be 
possible to execute FP68K either as a subprogram linked to an application 
program, or as system-provided utility. 

Because of the varying number of input parameters, it is impossible to 
call FP68K directly from Pascal, since the number of parameters is fixed when 
the EXTERNAL procedure is defined. In any case programmers should use the 
provided Pascal interface, called SANE (Standard Apple Numeric Environment). 

ELEMS68K has a similar design, but is configured as a separate package 
for modularity. 


Exit points 

Typically, FP68K. exits by clearing all input operands from the stack and 
jumping to the return address. 
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However, a 'halting' mechanism is provided whereby control is transferred 
from FP68K to an address saved in the floating-point state area (see below). 
This address should refer to a subprogram in the user's code space. When the 
halt routine is invoked, the top of the stack is a word containing the number 
of bytes of parameters (including the return address) on the stack when FP58K 
was originally called. Beyond that word is the exact stack frame from when 
FP68K was originally called. 

ELEMS68K has no built-in halt mechanism, though a subsidiary FP68K 
operation may halt* , 


State area 

ELEMS68K maintains no static state. FP68K maintains 3 words of static 
state across invocations. The first word contains mode and flag bits, much 
like the CPU Status Register. The next long word is the user trap address. 
There are two important issues! where is the state area and how is it 
initialized? 

The state area may be a fixed area in memory, as in MAC, or at a fixed 
offset from a register like A6, as in LISA, or in some user area if FP68K is 
linked as a subroutine. The state area may even be kept within FP68K itself, 
though this makes the code self— modifying and thus NON— REENTRANT. 

In multi— process environments, care must be taken to see that different 
state areas are kept for the different processes (again, think of the CPU 
Status Register). For example, if the state area is kept in a fixed location 
in memory, it must be swapped each time a new process is swapped in. 

The location of the state area must be known at ASSEMBLY TIME. As 
indicated in the programmer's guide document, the code must be set up for the 
particular host environment. 

When a new process is started up, the state area must be initialized. 
Fortunately, this is easy. Just clear to 0 the first word of the state area 
(i.e. the mode and flag word). 


CPU Condition Code Register 

The Comparison operation leaves the CCR in a well-defined state. After 
Comparison, the CCR is set for a conditional branch, although the flags ^are 
used in a way different from the integer CPU comparisons; see the "User's 
Guide" for details. 


CPU Register DO 

The Remainder operation leaves the low-order integer quotient (between 
-127 and +127) in DO.W. The high half of DO.L is undefined. This intrusion 
into the register file is extremely valuable in argument reduction — the 
principal use of Remainder. The state of DO- after an invalid remainder is 
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SANE 


There is a SANE (Standard Apple Numeric Environment) library of utility 
functions based on FP68K, as well as a corresponding Elems library based on 
ELEMS68K. These libraries are supported on Apple III Pascal systems as well. 
The library provides access to the package from (Lisa) Pascal* Aside from 
support of basic arithmetic and elementary functions, the utilities manipulate 
the modes and flags and provide ASCII < — > floating-point conversions. All 
applications software should use this package because of its high degree of 
portability. 

Assembly language programmers will invoke FP68K and ELEMS68K directly but 
will depend on some library for routines to convert between ASCII strings and 
the canonical decimal format which FP68K recognizes. A set of mnemonic MACROS 
has been provide to expedite assembly coding. 


Compiling Pascal programs 

A Pascal program which exploits the SANE and Elems interfaces must 
include lines such as 

uses {$U <some volume >: SANE. OBJ} SANE; 
uses ($U <some volume>: ELEMS. OBJ} Elems; 
in order to gain access to the types and procedures defined there. Then the 
program must be linked with SANE. OBJ and ELEMS. OBJ (the Pascal parts of the 
interface), as well as SANEASM. OBJ and ELEMS ASM. OBJ (the assembly language 
parts of the interface). 


Pascal procedures 

Programmers should consult the INTERFACE section of the SANE and Elems 
interfaces (files SANE. TEXT and ELEMS. TEXT) in the following pages. This 
interface reflects the architecture discussed in the "User's Guide*'. It is 
two-address, with the destination operand in the extended format except for 
format conversions conversions. 


Macros 


A set of macros provides direct contact with the arithmetic package, 
using the interface described in the "User's Guide". The macros take care of 
the opcode and the JSR, but the programmer must explicity push the required 
argument addresses. The macros do not take effective address arguments and 
push them itself because of the problems that arise if the destination operand 
is given as an offset from SP (which changes when the first operand address is 
pushed). The macros are listed after the Pascal interface. 
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Sample program 

The test programs ITxxx . TEXT , IOxxx . TEXT , and TDFP . TEXT provide a 
nontrivial view of how to use the Pascal interface to FP68K and ELEMS68K. 


ft 
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{“he "SANE Interface" } 

{“fo '28 December 1982'Page % 'Apple Confidential' } 

{$C Copyright Apple Computer, 1982 } 

{Macintosh version.} 

UNIT Sane; 

INTERFACE 

CONST 

SIGDIGLEN =20; { Maximum length of SigDig. } 

DECSTRLEN =80; { Maximum length of DecStr. } 


TYPE 


** Numeric types. 


Single = array [0..1] of integer; 
Double = array [0..3] of integer; 
Comp = array (0..3] of integer; 
Extended ■ array [0..4] of integer; 


{ 

** Decimal string type and intermediate decimal type, 

** representing the value: 

** (-l)“sgn * 10 “exp * dig 

} 


SigDig = string [SIGDIGLEN]; 

DecStr = string [DECSTRLEN]; 

Decimal = record 

sgn : 0..1; { Sign (0 for pos, 1 for neg). } 

exp : integer; { Exponent. } 

sig : SigDig { String of significant digits. } ^ 

end ; 


{ “ne 16 } 

** Modes, flags, and selections. 

** NOTE: the values of the style element of the DecForm record 
** have different names from the PCS version to avoid name 
** conflicts. 


Environ = integer; 

RoundDir = (TONEAREST, UPWARD, DOWNWARD, TOWARDZERO); 

RelOp = (GT, LT, GL, EQ, GE, LE, GEL, UNORD); 

{ > < <> = >= <= <=> } 

Exception = (INVALID, UNDERFLOW, OVERFLOW, DIVBYZERO, 

INEXACT) ; 
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/^s. 


NumClass = (SNAN, QNAN, INFINITE, ZERO, NORMAL, DENORMAL); 
DecForm = record 

style : (FloatDecimal , FixedDecimal) ; 
digits : integer 

end; 


Pne 35 } 

{ 

** Two address, extended-based arithmetic operations. 

} 






procedure AddS 

(x : 

Single ; 

var 

.y 

procedure 

AddD 

(x : 

Double ; 

var 

y 

procedure 

AddC 

(x : 

Comp; 

var 

y 

procedure 

AddX 

(x : 

Extended ; 

var 

y 

{ y 

! y + 

x } 




procedure 

SubS 

(x : 

Single; 

var 

y 

procedure 

SubD (x : 

Double ; 

var 

y 

procedure 

SubC 

(x : 

Comp; 

var 

y 

procedure 

SubX ( x : 

Extended ; 

var 

y 

{ y := 

* y - 

x } 




procedure MulS 

(x : 

Single ; 

var 

y 

procedure 

MulD (x : 

Double ; 

var 

y 

procedure MulC 

(x : 

Comp ; 

var 

y 

procedure 

MulX (x : 

Extended ; 

var 

y 

{ y :« y * 

X } 




procedure 

DivS 

(x : 

Single; 

var 

y 

procedure 

DivD (x : 

Double ; 

var 

y 

procedure 

DivC 

(x : 

Comp ; 

var 

y 

procedure 

DivX (x : 

Extended ; 

var 

y 


{ y :» y / x } 


Extended ) ; 
Extended ) ; 
Extended) ; 
Extended ) ; 


Extended ) ; 
Extended ) ; 
Extended ) ; 
Extended) ; 


Extended ) ; 
Extended ) ; 
Extended ) ; 
Extended ) ; 


Extended ) ; 
Extended ) ; 
Extended ) ; 
Extended ) ; 


function CmpX (x 
{ x r y } 


Extended; r : RelOp; 

y : Extended) : boolean; 


function RelX (x, y : Extended) : RelOp; 

{ x RelX y, where RelX in [GT, LT, EQ, UNORD] } 


{~ne 18 } 

{ 

** Conversions between Extended and the other numeric types, 

** including the types integer and Longint. 


procedure I2X (x : integer; var y : 

procedure S2X (x : Single; var y : 

procedure D2X (x : Double; var y : 

procedure C2X (x : Comp; var y : 

procedure X2X (x : Extended; var y : 

{ y := x (arithmetic assignment) 


Extended ) ; 
Extended ) ; 
Extended ) ; 
Extended ) ; 
Extended ) ; 
} 


1 November 1982 


Apple Confidential 



SANE Interface 


10 


procedure X2I (x : Extended; var y : integer); 

procedure X2S (x : Extended; var y : Single); 

procedure X2D (x : Extended; var y : Double); 

procedure X2C (x : Extended; var y : Comp); 

{ y := x (arithmetic assignment) } 

{~ne 9 } 

{ 7 

** These conversions apply to 68K systems only. Longint is 

** a 32-bit two's complement integer. 

} 

procedure L2X (x : Longint; var y : Extended); 

procedure X2L (x : Extended; var y : Longint); 

{ y := x (arithmetic assignment) } 

{ ~ne 17 } 

{ 7 

** Conversions between the numeric types and the intermediate 

** decimal type. 

} 

procedure S2Dec (f : DecForm; x : Single; var y : Decimal); 

procedure D2Dec (f : DecForm; x : Double; var y : Decimal); 

procedure C2Dec (f : DecForm; x : Comp; var y : Decimal); 

procedure X2Dec (f : DecForm; x : Extended; var y : Decimal); 

{ y := x (according to the format f) } 

procedure Dec2S (x : Decimal; var y : Single); 

procedure Dec2D (x : Decimal; var y : Double); 

procedure Dec2C (x : Decimal; var y : Comp); 

procedure Dec2X (x : Decimal; var y : Extended); 

{ y := x } 

{*ne 18 } 

{ 

** Conversions between the numeric types and strings. 

** (These conversions have a built-in scanner /parser to convert 
** between the intermediate decimal type and a string.) 

} 

procedure S2Str (f : DecForm; x : Single; var y : DecStr); 

procedure D2Str (f : DecForm; x : Double; var y : DecStr); 

procedure C2Str (f : DecForm; x : Comp; var y : DecStr); 

procedure X2Str (f : DecForm; x : Extended; var y : DecStr); 

{ y x (according to the format f) } 

procedure Str2S (x : DecStr; var y : Single); 

procedure Str2D (x : DecStr; var y : Double); 

procedure Str2C (x : DecStr; var y : Comp); 

procedure Str2X (x : DecStr; var y : Extended); 

{ y x } 
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{~ne 31 } 

{ 

** Numerical 'library' procedures and functions. 


procedure RemX (x : Extended; var y : Extended; 

var quo : integer); 

{ new y := remainder of ((old y) / x), such that 
| new y | <=» |x| / 2; 

quo := low order seven bits of integer quotient y / x, 

so that -127 <= quo <= 127 . } 

procedure SqrtX (var x : Extended); 

{ x := sqrt (x) } 

procedure RintX (var x : Extended); 

{ x :=• rounded value of x } 
procedure NegX (var x : Extended); 

{ x := -x } 

procedure AbsX (var x : Extended); 

{ x :» | x | } 

procedure CpySgnX (var x : Extended; y : Extended); 

{ x := x with the sign of y } 


procedure NextS (var x : Single; y : Single); 

procedure NextD (var x : Double; y : Double); 

procedure NextX (var x : Extended; y : Extended); 

{ x :=* next representable value from x toward y } 

function ClassS (x : Single; var sgn : integer) : NumClass; 

function ClassD (x : Double; var sgn : integer) : NumClass; 

function ClassC (x : Comp; var sgn : integer) : NumClass; 

function ClassX (x : Extended; var sgn : integer) : NumClass; 

{ sgn := sign of x (0 for pos, 1 for neg) } 


procedure ScalbX (n : integer; var y : Extended); 

{ y :=» y * 2~n } 

procedure LogbX (var x : Extended); 

{ returns unbiased exponent of x } 

{ ~ne 16 } 

** Manipulations of the static numeric state. 

} 


procedure SetRnd (r : RoundDir); r 

procedure SetEnv (e : Environ); 
procedure ProcExit(e : Environ); 

function GetRnd : RoundDir; 
procedure GetEnv (var e : Environ); 
procedure ProcEntry (var e : Environ); 

function TestXcp (x : Exception) : boolean; 
procedure SetXcp (x : Exception; OnOff : boolean); 
function TestHlt (x : Exception) : boolean; 
procedure SetHlt (x : Exception; OnOff : boolean); 
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{ r > 

rsp 32767 } 

{ } 


IMPLEMENTATION 

{$1 SANE IMP . TEXT } 


END 


{- 


J 
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{$C Copyright Apple Computer Inc., 1983 } 
UNIT Elems; 

{ Macintosh version. } 

INTERFACE 

USES 


fS 




{?U OBJ: SANE. OBJ } 

SANE { Standard Apple Numeric Environment } ; 

procedure Log2X (var x : Extended); 

{ x := log2 (x) } 

procedure LnX (var x : Extended); 

{ x :» In (x) } 

procedure LnlX (var x : Extended); 

( x := In (1 + x) } 

procedure Exp2X (var x : Extended); 

{ x 2~x } 

procedure ExpX (var x : Extended); 

{ x := e~x } 

procedure ExplX (var x : Extended); 

{ x :* e~x - 1 } 

procedure XpwrI (i : integer; var x : Extended); 

{ x x~i } 

procedure XpwrY (y : Extended; var x : Extended); 

{ x :=» x~y } 

procedure Compound (r, n : Extended; var x : Extended); 
{ x := (1 + r)~n } 

procedure Annuity (r, n : Extended; var x : Extended); 

{ x :• (1 - (1 + r)“-n) / r } 

procedure SinX (var x : Extended); 

{ x :■ sin(x) } 

procedure CosX (var x : Extended); 

{ x := cos(x) } 

procedure TanX (var x : Extended); 

{ x := tan(x) } 


1 November 1982 


Apple Confidential 



El eras Interface 


14 


procedure AtanX (var x : Extended); 

{ x atan(x) } 

procedure NextRandom (var x : Extended); 
{ x :■ next random (x) } 


($P 

IMPLEMENTATION 


procedure Log2X { (var x : Extended) } ; EXTERNAL; 
procedure LnX { (var x : Extended) } ; EXTERNAL; 
procedure LniX { (var x : Extended) } ; EXTERNAL; 
procedure Exp2X { (var x : Extended) } ; EXTERNAL; 
procedure ExpX { (var x : Extended) } ; EXTERNAL; 
procedure ExplX { (var x : Extended) } ; EXTERNAL; 


Since Elems implementation expects pointer to integer argument, 
use this extra level of interface. 

} 

procedure Xpwrlxxx(var i s integer; var x : Extended); EXTERNAL; 

procedure XpwrI { (i : integer; var x : Extended) } ; 

begin 

Xpwrlxxx(i, x); 

end; 


procedure XpwrY { (y : Extended; var x : Extended) } ; EXTERNAL; 
procedure Compound { (r, n : Extended; var x • Extended) } ; EXTERNAL; 
procedure Annuity { (r, n : Extended; var x : Extended) } ; aXTERNAL; 


procedure SinX { (var x : Extended) } ; EXTERNAL 
procedure CosX { (var x : Extended) } ; aXTERNAL 
procedure TanX { (var x : Extended) } ; EXTERNAL 
procedure AtanX { (var x : Extended) } ; EXTERNAL 
procedure NextRandom { (var x : Extended) } ; EXTERNAL 


END 
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These macros give assembly language access Co the Mac 
floating-point arithmetic routines. The arithmetic has 
just one entry point. It is typically accessed through 
the tool trap _FP68K, although a custom version of the 
package may be linked as an object file, in which case 
the entry point is the label ZFP68K. 

All calls to the arithmetic take the form: 

PEA <source address> 

PEA destination address> 

MOVE.W <opcode>,-( SP) 

_FP68K 

All operands are passed by address. The <opcode> word 
specifies the instruction analogously to a 68000 machine 
instruction. Depending on the instruction, there may be 
from one to three operand addresses passed. 

This definition file specifies details of the <opcode> 
word and the floating point state word, and defines 
some handy macros. 

Modification history: 

29AUG82: WRITTEN BY JEROME COONEN 

130CT82 : FB CONSTRANTS ADDED (JTC) 

28DEC82: LOGB, SCALB ADDED, INF MODES OUT (JTC). 
29APR83 : ABS, NEG, CPYSGN, CLASS ADDED (JTC). 
03MAY83 : NEXT, SETXCP ADDED (JTC). 

28MAY83 : ELEMENTARY FUNCTIONS ADDED (JTC). 

04JUL83: SHORT BRANCHES, TRIG AND RAND ADDED (JTC). 
01N0V83: PRECISION CONTROL MADE A MODE (JTC). 


This constant determines whether the floating point unit 
is accessed via the system dispatcher after an A-line 
trap, or through a direct subroutine call to a custom 
version of the package linked directly to the application. 


ATRAP 


.EQU 

BTRAP 


.EQU 


.MACRO 

JSRFP 


.IF 

FP68K 

.ELSE 

ATRAP 


.REF 

FP68K 


JSR 

FP68K 


. ENDC 
.ENDM 
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•MACRO JSRELEMS 

. IF BTRAP 

_ELEMS68K 

• ELSE 

. REF ELEMS68K 

JSR ELEMS68K 

. ENDC 

• ENDM 


OPERATION MASKS: bits $00 IF of the operation word 
determine the operation* There are two rough classes of 
operations: even numbered opcodes are the usual 


; arithmetic 
; arithmetic 

operations 
or utility 

and odd numbered opcodes are non- 
operations. 

9 

FOADD 

• EQU 

$0000 

FOSUB 

• EQU 

$0002 

FOMUL 

• EQU 

$0004 

FODIV 

• EQU 

$0006 

FOCMP 

• EQU 

$0008 

FOCPX 

• EQU 

$000A 

FOREM 

• EQU 

$000C 

FOZ2X 

• EQU 

$000E 

F0X2Z 

• EQU 

$0010 

FOSQRT 

• EQU 

$0012 

FORTI 

• EQU 

$0014 

FOTTI 

• EQU 

$0016 

FOSCALB 

• EQU 

$0018 

FOLOGB 

• EQU 

$001 A 

FOCLASS 

• EQU 

$001C 

; UNDEFINED 

• EQU 

$001E 

FOSETENV 

• EQU 

$0001 

FOGETENV 

• EQU 

$0003 

FOSETTV 

• EQU 

$0005 

FOGETTV 

• EQU 

$0007 

FOD2B 

• EQU 

$0009 

F0B2D 

• EQU 

$000B 

FONEG 

• EQU 

$000D 

FOABS 

• EQU 

$000F 

FOCPYSGNX 

• EQU 

$0011 

FONEXT 

• EQU 

$0013 

FOSETXCP 

• EQU 

$0015 

FOPROCENTRY 

• EQU 

$0017 

FOPROCEXIT 

• EQU 

$0019 

FOTESTXCP 

• EQU 

$00 IB 

; UNDEFINED 

• EQU 

$00 ID 

; UNDEFINED 

• EQU 

$00 IF 
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OPERAND FORMAT MASKS: bits $3800 determine the format of 
any non-extended operand. 


FFEXT 

.EQU 

$0000 

; extended — 

80-bit 

float 

FFDBL 

.EQU 

$0800 

; double — 

64 -bit 

float 

FFSGL 

.EQU 

$1000 

; single 

32-bit 

float 

FFINT 

.EQU 

$2000 

; integer — 

16-bit 

integer 

FFLNG 

.EQU 

$2800 

; long int — 

32-bit 

integer 

FFCOMP 

.EQU 

$3000 

; accounting — 64-bit int 


t 


Bit indexes for error and halt bits and rounding modes in 
the state word. The word is broken down as: 


$8000 — unused 


$6000 — rounding modes 

$0000 — to nearest 
$2000 — toward +infinity 
$4000 — toward -infinity 
$6000 — toward zero 


$1F00 


— error flags 

$1000 — inexact 

$0800 — division by zero 

$0400 — overflow 

$0200 — underflow 

$0100 — invalid operation 


$0080 — result of last rounding 

$0000 — rounded down in magnitude 
$0080 -- rounded up in magnitude 


$0060 — precision control 
$0000 — extended 
$0020 — double 
$0040 — single 
$0060 — ILLEGAL 

$001F — - halt enables, corresponding to error flags 


The bit indexes are based on the byte halves of the state 
word . 


FBINVALID 

.EQU 

0 

FBUFL0W 

.EQU 

1 

FBOFLOW 

.EQU 

2 

FBDIVZER 

.EQU 

3 

FBINEXACT 

• EQU 

4 

FBRNDLO 

.EQU 

5 

FBRNDHI 

.EQU 

6 

FBLSTRND 

.EQU 

7 

FBDBL 

.EQU 

5 


invalid operation 
underflow 
overflow 
division by zero 
inexact 

low bit of rounding mode 
high bit of rounding mode 
last round result bit 
double precision control 
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FBSGL 


; single precision control 


FLOATING CONDITIONAL BRANCHES: floating point comparisons 
set the CPU condition code register (the CCR) as follows; 
relation X N Z V C 


equal 00100 

less than 11001 

greater than 00000 

unordered 0 0 0 l 0 

The macros below define a set of so-called floating 
branches to spare the programmer repeated refemces to the 
the table above. 


.MACRO 

FBEQ 

BEQ 

.ENDM 

%1 

.MACRO 

FBLT 

BCS 

.ENDM 

%1 

.MACRO 

FBLE 

BLS 

.ENDM 

%1 

.MACRO 

FBGT 

BGT 

.ENDM 

%1 

.MACRO 

FBGE 

BGE 

.ENDM 

%1 

.MACRO 

FBULT 

BLT 

.ENDM 

%1 

.MACRO 

FBULE 

BLE 

.ENDM 

%1 

.MACRO 

FBUGT 

BHI 

.ENDM 

%1 

.MACRO 

FBUGE 

BCC 

.ENDM 

%1 

.MACRO 

FBU 

BVS 

%1 
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.ENDM 


.MACRO 

FBO 

BVC 

%1 

.ENDM 


.MACRO 

FBNE 

BNE 

%1 

.ENDM 


.MACRO 

FBUE 

BEQ 

11 

BVS 

%1 

.ENDM 


.MACRO 

FBLG 

BNE 

% 1 

BVC 

11 


«ENDM 


; Short branch versions. 

.MACRO FBEQS 
BEQ.S % 1 
. ENDM 


.MACRO 

FBLTS 

BCS.S 

.ENDM 

%1 

.MACRO 

FBLES 

BLS.S 

.ENDM 

% 1 

.MACRO 

FBGTS 

BGT.S 

.ENDM 

11 

.MACRO 

FBGES 

BGE.S 

% 1 


. ENDM 


.MACRO 

FBULTS 

BLT.S 

11 

.ENDM 


.MACRO 

FBULES 

BLE.S 

11 

.ENDM 


.MACRO 

FBUGTS 

BHI.S 

11 

.ENDM 
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.MACRO 

FBUGES 

BCC.S 

.ENDM 

%1 

.MACRO 

FBUS 

BVS.S 

.ENDM 

%1 

.MACRO 

FBOS 

BVC.S 

.ENDM 

XI 

.MACRO 

FBNES 

BNE.S 

.ENDM 

%1 

.MACRO 

FBUES 

BEQ.S 

%1 

BVS.S 

.ENDM 

XI 

.MACRO 

FBLGS 

BNE.S 

XI 

BVC.S 

.ENDM 

XI 


OPERATION MACROS: 

THESE MACROS REQUIRE THAT THE OPERANDS' ADDRESSES 
FIRST BE PUSHED ON THE STACK. THE MACROS CANNOT 
THEMSELVES PUSH THE ADDRESSES SINCE THE ADDRESSES 
MAY BE SP-RELATIVE, IN WHICH CASE THEY REQUIRE 
PROGRAMMER CARE. 

OPERATION MACROS: operand addresses should already be on 
Che stack, with the destination address on top. The 
suffix X, D, S, or C determines the format of the source 
operand — extended, double, single, or computational 
respectively; the destination operand is always extended. 


Addition. 


.MACRO FADDX 

MOVE.W #FFEXT+FOADD , -( SP ) 

JSRFP 

.ENDM 

.MACRO FADDD 

MOVE.W #FFDBL+FOADD , -( SP ) 

JSRFP 

.ENDM 
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.MACRO FADDS 

MOVE.W #FFSGL+FOADD,-(SP) 
JSRFP 
• ENDM 

.MACRO FADDC 

MOVE.W #FFCOMP+FOADD , -( SP) 

JSRFP 

.ENDM 


Subtraction. 

.MACRO FSUBX 

MOVE.W #FFEXT+FOSUB,-(SP) 

JSRFP 

.ENDM 

.MACRO FSUBD 

MOVE.W #FFDBL+FOSUB,-(SP) 

JSRFP 

.ENDM 

.MACRO FSUBS 

MOVE . W #FFSGL+FOSUB , -( SP ) 

JSRFP 

.ENDM 

.MACRO FSUBC 

MOVE.W #FFCOMP+FOSUB , -( SP ) 

JSRFP 

.ENDM 


Multiplication. 


.MACRO FMULX 

MOVE . W #FFEXT+FOMUL , -( SP ) 
JSRFP 
• ENDM 

.MACRO FMULD 

MOVE . W #FFDBL+FOMUL , -( SP ) 

JSRFP 

.ENDM 

.MACRO FMULS 

MOVE . W #FFSGL+FOMUL , -( SP ) 

JSRFP 

.ENDM 
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.MACRO FMULC 

MOVE.W #FFCOMP+FOMUL,-( SP) 

JSRFP 

.ENDM 


9 

Division. 


.MACRO 

FDIVX 

MOVE.W 

JSRFP 

.ENDM 

#FFEXT+FODIV,-(SP) 

.MACRO 

FDIVD 

MOVE.W 

JSRFP 

.ENDM 

#FFDBL+FODIV , -( SP ) 

.MACRO 

FDIVS 

MOVE.W 

JSRFP 

.ENDM 

#FFSGL+FODIV,-(SP) 

.MACRO 

FDIVC 

MOVE.W 

JSRFP 

.ENDM 

#FFCOMP+FODIV,-( SP) 

9 

; Compare, signaling no exceptions. 

.MACRO 

FCMPX 

. MOVE.W 
JSRFP 
.ENDM 

//FFEXT+FOCMP , -( SP ) 

.MACRO 

FCMPD 

MOVE.W 

JSRFP 

#FFDBL+FOCMP , -( SP) 

.ENDM 


.MACRO 

FCMPS 

MOVE.W 

JSRFP 

.ENDM 

#FFSGL+FOCMP,-(SP) 

.MACRO 

FCMPC 

MOVE.W 

JSRFP 

.ENDM 

0FFCOMP+FOCMP , -( SP ) 
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; Compare, signaling invalid operacion if Che two operands 
; are unordered. 

.MACRO 

FCPXX 

MOVE.W 
JSRFP 
. ENDM 

#FFEXT+FOCPX,-(SP) 

.MACRO 

FCPXD 

MOVE.W 

JSRFP 

.ENDM 

#FFDBL+FOCPX,-(SP) 

.MACRO 

FCPXS 

MOVE.W 

JSRFP 

.ENDM 

#FFSGL+FOCPX,-(SP) 

.MACRO 

FCPXC 

MOVE.W 

JSRFP 

.ENDM 

#FFCOMP+FOCPX , -( SP ) 

9 ' 

Remainder. The remainder is placed in che descinacion. 

and che low bics of che inceger quotient are placed in 

Che low word 

of regiscer DO. 

9 

.MACRO 

FREMX 

MOVE.W 
JSRFP 
• ENDM 

#FFEXT+FOREM, -( SP) 

.MACRO 

FREMD 

MOVE.W 

JSRFP 

.ENDM 

#FFDBL+FOREM, -( SP) 

.MACRO 

FREMS 

MOVE.W 

JSRFP 

.ENDM 

#FFSGL+FOREM , -( SP ) 

.MACRO 

FREMC 

MOVE.W 

0FFCOMP+FOREM , -( SP ) 

JSRFP 


.ENDM 

9 



Compare Che source operand Co ctie excended format and 
place in Che destination. 
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.MACRO FX2X 

MOVE.W it FFEXT+F0Z2X , -( SP ) 

JSRFP 
. ENDM 

.MACRO FD2X 

MOVE.W #FFDBL+FOZ2X,-(SP) 

JSRFP 

.ENDM 

t 

.MACRO FS2X 

MOVE.W #FFSGL+FOZ2X, -( SP ) 

JSRFP 

.ENDM 

.MACRO FI2X ; 16-bit integer 

MOVE.W it FFINT+FOZ2X , -( SP ) 

JSRFP 

.ENDM 

.MACRO FL2X ; 32-bit integer 

MOVE . W 0FFLNG+FOZ2X , -( SP ) 

JSRFP 

.ENDM 

.MACRO FC2X 

MOVE.W #FFCOMP+FOZ2X, -( SP ) 

JSRFP 

.ENDM 


; Convert the extended source operand to 
; format and place in the destination. 

the specified 

.MACRO 

FX2D 


MOVE.W 

JSRFP 

.ENDM 

#FFDBL+FOX2Z,-(SP) 


.MACRO 

FX2S 


MOVE.W 

JSRFP 

.ENDM 

#FFSGL+FOX2 Z , -( SP ) 


.MACRO 

FX2I 

; 16-bit integer 

MOVE.W 

JSRFP 

.ENDM 

i/FFINT+FOX2Z,-(SP) 


.MACRO 

FX2L 

; 32-bit integer 

MOVE.W 

JSRFP 

#FFLNG+FOX2Z , -( SP ) 
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.ENDM 

.MACRO FX2C 

MOVE.W #FFCOMF+FOX2Z , -( SP) 

JSRFP 

.ENDM 


Miscellaneous operations applying only to extended 
operands. The input operand is overwritten with the 
computed result. 


; Square root. 

.MACRO FSQRTX 
MOVE.W #FOSQRT,-(SP) 

JSRFP 

.ENDM 

Round to integer, according to the current rounding mode. 
.MACRO FRINTX 
MOVE.W #FORTI,-( SP) 

JSRFP 

.ENDM 

; Round to integer, forcing rounding toward zero. 

.MACRO FTINTX 
MOVE.W #FOTTI,-(SP) 

JSRFP 

.ENDM 

; Set the destination to the product: 

; (destination) * 2~( source) 

; where the source operand is a 16-bit integer. 

•MACRO FSCALBX 

MOVE.W #FFINT+FOSCALB , -( SP ) 

JSRFP 

.ENDM 

; Replace the destination with its exponent, converted to 
; the extended format* 

.MACRO FLOGBX 
MOVE.W #FOLOGB,-( SP) 

JSRFP 

.ENDM 


Non-arithmetic sign operations on extended operands. 


; Negate . 

.MACRO FNEGX 
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MOVE.W #FONEG,-(SP) 

JSRFP 

*ENDM 

; Absolute value. 

.MACRO FABSX 
MOVE.W #FOABS,-(SP) 

JSRFP 

.ENDM 

; Copy the sign of the destination operand onto the sign of 
; the source operand. Note that the source operand is 
; modified. 

.MACRO FCPYSGNX 
MOVE.W # FOCPY SGN , -( SP ) 

JSRFP 

.ENDM 


The nextafter operation replaces the source operand with 
its nearest representable neighbor in the direction of the 
destination operand. Note that both operands are of the 
the same format, as specified by the usual suffix. 


.MACRO 

FNEXTS 

MOVE.W 

JSRFP 

.ENDM 

#FFSGL+FONEXT , -( SP ) 

.MACRO 

FNEXTD 

MOVE.W 

#FFDBL+FONEXT , -( SP ) 

JSRFP 

.ENDM 


.MACRO 

FNEXTX 

MOVE.W 

JSRFP 

.ENDM 

#FFEXT+FONEXT , -( SP ) 


The classify operation places an integer in the 
destination. The sign of the integer is the sign of the 
source. The magnitude is determined by the value of the 
source, as indicated by the equates. 


FCSNAN 

.EQU 

1 

signaling NAN 

FCQNAN 

.EQU 

2 

quiet NAN 

FCINF 

.EQU 

3 

infinity 

FCZERO 

.EQU 

4 

zero 

FCNORM 

.EQU 

5 

normal number 

FCDENORM 

.EQU 

6 

denormal number 
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.MACRO FCLASSS 

MOVE.W #FFSGL+FOCLASS ,-( SP) 

JSRFP 

.ENDM 

.MACRO FCLASSD 

MOVE.W #FFDBL+FOCLASS,-(SP) 

JSRFP 

.ENDM 

.MACRO FCLASSX 

MOVE.W #FFEXT+FOCLASS, -( SP) 

JSRFP 

.ENDM 

.MACRO FCLASSC 

MOVE . W #FFCOMP+FOCLASS , -( SP ) 

JSRFP 

.ENDM 


These four operations give access to the floating point 
state (or environment) word and the halt vector address. 
The sole input operand is a pointer to the word or address 
to be placed into the arithmetic state area or read from 
it. 

.MACRO 

FGETENV 


MOVE.W 

#FOGETENV,-(SP) 


JSRFP 

.ENDM 



.MACRO 

FSETENV 


MOVE.W 

JSRFP 

.ENDM 

#F0SETENV , -( SP ) 


.MACRO 

FGETTV 


MOVE.W 

JSRFP 

.ENDM 

#F0GETTV,-< SP) 


.MACRO 

FSETTV 


MOVE.W 

JSRFP 

.ENDM 

> 

#FOSETTV,-(SP) 



Both FPROCENTRY and FPROCEXIT have one operand — a 
pointer to a word. The entry procedure saves the current 
floating point state in that word and resets the state 
to 0, that is all modes to default, flags and halts to 
OFF. The exit procedure performs the sequence: 
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1. Save current error flags in a temporary. 

2. Restore the state saved at the address given by 

the parameter. 

3. Signal the exceptions flagged in the temporary, 

halting if so specified by the newly 
restored state word. 

These routines serve to handle the state word dynamically 
across subroutine calls. 


.MACRO 

FPROCENTRY 


MOVE.W 
JSRFP 
. ENDM 

0FOPROCENTRY , -( SP ) 


.MACRO 

FPROCEXIT 


MOVE.W 

#FOPROCEXIT , -( SP ) 


JSRFP 



.ENDM 


— 


FSETXCP is a null arithmetic operation which stimulates 
the indicated exception. It may be used by library 
routines intended to behave like elementary operations. 
The operand is a pointer to an integer taking any value 
between FBINVALID and FBINEXACT. 

FTESTXCP tests the flag indicated by the integer pointed 
to by the input address. The integer is replaced by a 
Pascal boolean (word $0000"false, $0100*true) 


.MACRO 

FSETXCP 


MOVE.W 

#F0SETXCP , -( SP ) 


JSRFP 



.ENDM 



.MACRO 

FTESTXCP 


MOVE.W 

#FOTESTXCP,-(SP) 


JSRFP 


4 

.ENDM 




WARNING: PASCAL ENUMERATED TYPES, LIKE THOSE OF THE 
DECIMAL RECORD, ARE STORED IN THE HIGH-ORDER BYTE OF THE 
ALLOCATED WORD, IF POSSIBLE. THUS THE SIGN HAS THE 
INTEGER VALUE 0 FOR PLUS AND 256 (RATHER THAN L) 

FOR MINUS. 

3INARY -DECIMAL CONVERSION: The next routines convert 
between a canonical decimal format and the binary format 
specified. The decimal format is defined in Pascal as 

CONST 

SIGDIGLEN » 20; 
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TYPE 

SigDig = string [SIGDIGLEN] ; 

Decimal ■ record 

sgn : 0..1; 
exp : integer; 
sig : SigDig 

end; 

Note that Lisa Pascal stores the sgn in the high-order 
byte o£ the allotted word, so the two legal word values 
of sgn are 0 and 256. 


Decimal to binary conversion is governed by a format 
record defined in Pascal as: 

TYPE 

Dec Form » record 

style : (FloatDecimal, FixedDecimal ) ; 
digits : integer 

end; 

Note again that the style field is stored in the high- 
order byte of the allotted word. 

These are the only operations with three operands. The 
pointer to the format record is deepest in the stack, 
then the source pointer, and finally the destination 
pointer. 


.MACRO FDEC2X 
MOVE.W #FFEXT+F0D2B , -( SP ) 
JSRFP 
. ENDM 

.MACRO FDEC2D 

MOVE.W # FFDBL+F0D2 B , -( S P ) 

JSRFP 

.ENDM 

.MACRO FDEC2S 

MOVE.W #FFSGL+F0D2B,-( SP) 

JSRFP 

.ENDM 

.MACRO FDEC2C 

MOVE.W # FFC0MP+F0D2 B , -( SP ) 

JSRFP 

.ENDM 
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; Binary to decimal conversion. 


.MACRO FX2DEC 

MOVE.W #FFEXT+F0B2 D , -( SP ) 

JSRFP 

.ENDM 

.MACRO FD2DEC 

MOVE.W #FFDBL+FOB2D,-(SP) 

JSRFP 

.ENDM 

.MACRO FS2DEC 

MOVE.W //FFSGL+FOB2D, -( SP ) 

JSRFP 

.ENDM . 

.MACRO FC2DEC 

MOVE.W #FFCOMP+FOB2D , — ( SP ) 

JSRFP 

.ENDM 


Equates and macros for elementary functions. 


FOLNX 

.EQU 

$0000 

FOLOG2X 

.EQU 

$0002 

FOLN1X 

.EQU 

$0004 

FOLOG21X 

.EQU 

$0006 

FOEXPX 

.EQU 

$0008 

FOEXP2X 

.EQU 

$000A 

F0EXP1X 

.EQU 

$000C 

FOEXP21X 

.EQU 

$000 E 

FOXPWR1 

.EQU 

$8010 

FOXPWRY 

.EQU 

$8012 

FOCOMPOUNDX 

.EQU 

$C014 

FOANNUITYX 

.EQU 

$C016 

FOSINX 

.EQU 

$0018 

FOCOSX 

.EQU 

$001 A 

FOTANX 

.EQU 

$001C 

FOATANX 

.EQU 

$00 IE 

FORANDOMX 

.EQU 

$0020 

.MACRO 

FLNX 


MOVE.W 

# FOLNX, 

-(SP) 


JSRELEMS 

.ENDM 

.MACRO FLOG2X 
MOVE.W #FOLOG2X,-(SP) 
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JSRELEMS 
• ENDM 

.MACRO FLN1X 
MOVE.W #F0LN1X,-(SP) 
JSRELEMS 
.ENDM 

.MACRO FLOG21X 
MOVE.W #FOLOG21X,-(SP) 
JSRELEMS 
.ENDM 

.MACRO FEXPX 

MOVE . W #FOEXPX , -( SP ) 

JSRELEMS 

.ENDM 

.MACRO FEXP2X 
MOVE.W # FOEXP2X , -( SP ) 
JSRELEMS 
.ENDM 

.MACRO FEXP1X 
MOVE.W #F0EXP1X,-(SP) 
JSRELEMS 
.ENDM 

.MACRO FEXP21X 
MOVE.W #FOEXP21X,-( SP) 
JSRELEMS 
.ENDM 

.MACRO FXPWRI 

MOVE.W #FOXPWRI,-(SP) 

JSRELEMS 

.ENDM 

.MACRO FXPWRY 

MOVE . W #FOXPWRY , -( SP ) 

JSRELEMS 

.ENDM 

.MACRO FCOMPOUNDX 

MOVE.W #FOCOMPOUNDX,-(SP) 

JSRELEMS 

.ENDM 

.MACRO FANNUITYX 
MOVE.W #FOANNUITYX,-(SP) 
JSRELEMS 
.ENDM 

.MACRO FSINX 
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MOVE.W #FOSINX,-(SP) 
JSRELEMS 
• ENDM 

.MACRO FCOSX 
MOVE.W #FOCOSX,-(SP) 
JSRELEMS 
.ENDM 

.MACRO FTANX 
MOVE.W #FOTANX,-(SP) 
JSRELEMS 
.ENDM 

.MACRO FATANX 
MOVE.W #FOATANX,-(SP) 
JSRELEMS 


.MACRO FRANDOMX 
MOVE.W //FORANDOMX, “( SP ) 
JSRELEMS 
.ENDM 
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Introduction 

FP68K provides conversions between the extended floating-point format and 
three integer formats: 

intl6 — 16-bit two's complement 
int32 — 32-bit two's complement 

comp64 — 64-bit two's complement with the reserved value 
hexadecimal 8000000000000000 . 

One Pascal program, ITBATTERY.TEXT, tests all three conversions. This 
document describes how to use and, if necessary, modify the tests. 


Compiling and running 

ITBATTERY.TEXT uses the SANE interface (see the "High Level Interface" 
document, so it atust be linked with the SANE object files, as well as with the 
usual nonarithmetic Pascal run-time libraries (e.g. *MPASLIB on Lisa). The 
program will simply run to completion, with a Pascal HALT if an error is 
found; execution time may run to 13 minutes on a Lisa system. 


What is tested 

Each of the integer formats is tested in two phases. First, a collection 
of specific extended numbers is converted to the integer format, with tests 
for correct rounding and signaling of the invalid exception when appropriate. 
Then a set of 

integer — > extended — > integer 

conversions is run, with the input and output integers compared for equality. 
In the case of intl6, all 2~16 cases are run. However exhaustive testing of 
int32 and comp64 is infeasible so a loop is set up to do 2*16 tests from 
several starting points. 
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Introduction 


The most important and rigorous sat ol tests of FP68K is th« s “ ?* 
so-called IEEE test vectors. These tests, developed by the author while ^ 
Ziloff are used to test implementations of proposed standar .J , h 

donated*!* the* IEEE subcommittee 754 by Zilog Inc, and are now distributed by 
th« subcomil tt«. The tests have undergone major revision within Apple, 
thanks especially to Jim Thomas of PCSe 


Form of the tests 

Each vector is an ascii string describing an operation, th * 

result. For example, "linci" is the "Unci", 

under consideration) next larger than 1. When 1 i Written this 

Ihe result is “lulpl". just one unit “Vo^c £ 

^e £ iuy V t^:t“L b iur."1f“orji^ 0 ^ L^ptl r ““ 

S.SS : srjs s sss s £ « 

cleared up. 


Files 

The test vectors are contained in a family of files by the ^fj me 
TVxxxx .2. TEXT and TWxxx.2.TEXT. The "2" refers to version 2 ^ ^he tes . 
(V^on 1 was based on Draft 8.0 of the standard.) The file n.iST.TEXT is a 
of the test file names to be used in any given run of the test. rascal 
file TD68.TEXT with unit TD68FP.TEXT actually run the tests. These inter 
with FP68K exclusively through the SANE interface. 
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j Introduction 


Since the binary < — > conversions within FP68K approximate the 
mathematical identity operation, they lend themselves to certain types of 
self-testing. For example, if enough decimal digits are kept, then the 
conversion 

binary -— > decimal -—> binary 

is the identity mapping when^ results are rounded to nearest* The number of 
digits required turns out to be 9 for single and 17 for double. A similar 
test performs the first conversion rounding toward plus infinity and the 
second rounding toward minus infinity. In this case the final result may 
differ from the starting value by one unit in the direction of the latter 
rounding, so the program allows this discrepancy. 

This document describes the test files and how they can be run. For 
details of the underlying error analysis (which is quite subtle) see the paper 
"Accurate Yet Economical Binary-Decimal Conversions" by J. Coonen. 


Test programs 

The test programs are : 

IOS.TEXT 
IOSF . TEXT 
IOD.TEXT 
IODF « TEXT 
IONAN . TEXT 
IOPSCAN.TEXT 

The letter "S" and "D" distinguishes single and double tests. The IOS.TEXT 
and IOD.TEXT tests run with both rounding to nearest and the directed 
roundings. The "F" tests use fixed -format output rather than floating-format 
output for the intermediate decimal string. The IOPSCAN test is used to check 
the preformance of the printer and scanner used by SANE68, and included from 
file SAPSCAN.TEXT. The IONAN test checks the input and output conversion of 
some 20 stock NANs, and then allows the user to enter any decimal string to be 
converted to the three formats in three rounding modes. Neither IOPSCAN nor 
IONAN are self -checking; rather, the user must monitor their output. 

The tests cover extreme intervals where the decimal numbers are sparsest 
and densest with respect to the binary numbers. Sparse intervals have the 
form [10~N, 2~n] where the endpoints are nearly equal. Dense intervals have 
the corresponding form [2~m, 10 '"M] . 


Running the tests 

Each of the programs is compiled and run separately. The programs use 
the SANE interface. A test will HALT with a suitable diagnostic if the test 
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The single format cases are few enough that their tests can be cun 
overnight. However, the double format cases will run essentially forever 
since the number of interesting cases is so great. A. few overnight tests 
should be sufficient. 
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Background 

The so-called I/O routines for scanning and printing floating-point 
numbers in decimal form are complicated by subtle numerical issues and 
nettlesome design decisions. For example, even the simplest, stripped-down 
conversion routines require over one— third the code space (about 1.3K) of the 
rest of the FP68K binary floating-point package. With a full parser and 
formatter, the conversion routines are much larger. And it is unclear whether 
full routines would be flexible enough for use in different language systems 
and I/O-intensive applications like Visi-Calc. 

Where does the responsibility lie? This note argues that the core 
conversion routines, which are part of the arithmetic package, should be kept 
very simple. Above them — — somewhere in the system — — should be a full 
scanner and formatter available to languages and applications, but not forced 
upon them. This would lead to the most efficient use of code space and 
execution time. 


The Sad Truth 

Numerical I/O can be monstrous. Since each' computer language has its own 
grammar for floating-point numbers and its own cohventions for output format, 
it almost necessary for each language system on a computer to provide 
significant I/O support. Unfortunately, this may be layered upon the host 
system's I/O system. And it is not unusual (Apple III, for example) for a 
language compiler to use different conversion routines than the I/O system the 
compiled code utilizes. 

In another case, designers of the UNIX operating system attempted to 
route all conversion through the routines atof(), ascii to floating, and the 
pair ecvt(), fcvt() for floating and fixed conversion to ascii. But even this 
fairly clean design has led to VERY complicated software shells around atof, 
ecvt, and fcvt. Numerical accuracy aside, the complexity of just the 
character hacking is forbidding. 

One problem with the UNIX design lies in its failure to properly divide 
responsibility for the distinct processes involved in conversion, namely: 

1. Recognize floating-point strings (in compilers, ...) 

2. Translate strings to numerical values. 

3. Determine which output format (fixed or floating) is 
appropriate for a given value. 

4. Translate a numerical value to a string. 

The utilities atof() and ecvt( ) provide items 2 and 4. Item 3, printing a 
number in its "nicest” form is provided in rough form through ecvt(). But 
recognizing strings is left to each language compiler's lexical scanner. 
Unfortunately, after a scanner has parsed a floating decimal string, it passes 
it along to atof() where it is parsed once more. 
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A Proposal for Change 

(1) Support, at the arithmetic level, conversions between each of the 
available binary floating-point types and one decimal structure describable in 
Pascal as: 

{* 

** Low-level format of the floating decimal value : 

** (-l)~sgn * 10~exp * dig 

** The constant DECSTRLEN is 20 for MAC and 28 for III, since 
** the latter uses very high precision for intermediates. 

*} 

type 

DecStr * string [DECSTRLEN] 

Decimal * record 

sgn: 0..1; [0 for +, 1 for -} 

exp: integer; 
sig: DecStr 

end; 

(2) Rigidly specify the format of Decimal. sig for decimal to binary 
conversions, relying upon a lexical scanner to perform the first parse. The 
decimal value would depend upon the first character of decree. dig: 

'I' --> infinity 

’Nxxx...x' — > NAN, with optional ascii hex digits 0-9, A-F, a-f 
'O' — > zero 

'ddd...d' — > string of digits stripped of leading and trailing zeros 

The digit string would never be more than 20 digits long. If present, the 
20 -th digit would indicate the absence of nonzero trailing digits beyond the 
20-th (to aid in correct rounding). 

(3) Specify decimal output format through a structure like the Pascal: 

{* 

** Output format specifier. 

*} 

type 

DecForm * record 

style: (float, fixed); 
digits: integer, 
end ; ; 

For "float” conversions, digits is the number of significant digits to be 
delivered in Decimal. sig. For "fixed" conversions, count is the number of 
fraction digits to be converted (a negative count suppresses conversion of 
low-order integer digits). 

Sometimes it is desired to print a number in the nicest form possible for 
a given field width. For example, the string "1.23456789" conveys much more 
information in 10 characters than does "1 .2345e+04". Such conversions are 
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discussed in the next section. 

(4) Provide a scanner and formatter which, if not of most general use, 
provide models that can be tailored to a particular application. Samples are 
huilt into the implementation section of the SANE Pascal interface; they are 
contained in the file SAP SC AN. TEXT. 


Binary — > Decimal 

The family of routines: 

S2Dec 

D2Dec 

X2Dec 

C2Dec 

provide conversions to the Decimal record format described above. Special 
cases are keyed by the first character of Decimal. sig: 

'O' : zero 
•I' : infinity 

'N' : not-a-number, followed by optional ascii hex digits; if there are 
fewer than four, they are padded on the left with 0's. 

'?' : overflow of fixed-style format 

These must be used with a formatter to produce output strings. 

The family: 

. S2Str 
D2Str • 

X2Str 

C2Str 

uses the built-in formatter, Dec2Str, to generate ascii string output. 


Decimal — > Binary 

These conversions are povided by the complementary set of procedures: 
Dec2S, Dec2D, Dec2X, Dec2C, and Str2S, Str2D, Str2X, Str2C. In the case of 
the Dec2* conversions, the first character of Decimal. sig indicates special 
cases as noted above for *2Dec conversions. 


Infinity and NAN conversions 

Infinity is printed and read as a string of sign characters, "+++++" or 

H I* 


On input, NANs have the general form NAN'xxxx:yyy. • .y ' . The x's and y's 
should be ascii hex digits: 0-9, A-F, a-f. The string portion following NAN 
may be omitted. The x's are padded on the LEFT with 0's to width 4. The y's 
are padded on the RIGHT with 0's to the width of the NAN's significant bit 
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field. 

On output, NANs will be printed in the same format. Leading x*0 and 
trailing y*0 are omitted, but at least one x is printed. If all y“0, then the 
colon and the y field is dropped. 

Any unrecognizable string is converted to a NAN. 
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Background 

Applications like accounting spreadsheets typically need to display 
floating-point values in decimal form within a field of fixed width. For 
maximum readability, the output should be in integer or fixed-point format if 
possible, with floating-point format as a last resort. The idea is to avoid 
listing small integers in the abominable form 0.100000000000E1 reminiscent of 
computing in the McCarthy era. 


The problem 

Given a binary floating-point number X and an ascii field F, display X in 
the "nicest", most informative way within F. 


A proposal 

1. If X may be displayed in a subfield of F, pad X on the left with blanks. 

2. Display the sign of X only if it is 

3. If X is an integer and F is wide enough to accommodate X, then display X as 
an integer, without a trailing 

4. Else if X has nonzero integer and fraction parts and F is wide enough to 

accommodate at least the integer part of F and its trailing then display 

X in the fixed-point form ZZZZ.YYYY with as many fraction digits as F will 
accommodate, up to a maximum of 17 significant digits. 

3. Else if | X | < 1 and F is wide enough that X may be displayed in the form 
0.00000ZZZZZ with no more Os just to the right of the decimal point than 
digits following those Os, then display X in that fixed-point form with up to 
17 significant digits. 

6. Finally, if all the above fail, then display X in the floating-point form 
Z.ZZZZZEYYY with as many significant digits up to 17 as F will accommodate, 
taking into account the width of the exponent field, including its possible 
sign. Display the sign of the exponent field only if it is 


An implementation 

The above choices depend on detailed knowledge of the magnitude of X. 

For example, in producing floating-point output, it is necessary to know the 
number of spaces that will be occupied by the decimal exponent (with sign, it 
could be 1 to 5) in order to know how many significant digits to which to 
round X. In the worst case, this could mean several calls upon the low-level 
conversion routine until the proper output is finally obtained. 

One easy way to bypass these problems, and keep the fundamental 
conversion routine simple, is perform the binary -> decimal conversion in two 
stages. First convert the binary value X to the SANE decimal form: 
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type 

DecStr - string (DECSTRLEN} ; { length is 20 for MAC } 

Decimal * record 

sgn: integer; {0 for + , nonzero for -} 

exp: integer; {as though decimal is at the right of...} 

sig: DecStr 

end; 

If the conversion is performed with rounding toward 0, conversion style * 
float, and digit count - 19, and if the inexact exception flag is cleared 
before the conversion, then the 19-digit result may be correctly rounded to 
the desired width after the ultimate output format is determined. Since no 
more than 17 digits will ever be displayed (recall that 17 digits suffice to 
distinguish double format binary numbers), the 19 digits together with the 
inexact exception flag permit correct rounding. 

The second step of the conversion decides, on the basis of the 
intermediate decimal form, which format is appropriate. Then the decimal 
value is rounded (in decimal!) and displayed as desired. Note that this 
scheme has as a happy byproduct the ability to round in the (time-honored?) 
"add half and chop" manner that is unavailable within Apple arithmetic itself. 
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In the interest of compatibility of the floating-point arithmetic on 
Apples II/III and Mac/(Lisa?), the following GRITTY DETAILS were discussed on 
June 29. This is an update on the decisions made then. 

1. Distinguishing signaling and quiet NANs: use the leading fraction bit, 
0-quiet and 1 -signaling. 

2. Explicit leading bit of extended NANs and INFs: ignore it, that is decide 
whether NAN or INF on the basis of the fraction bits only. 

t 

3. Quiet NANs have an 8-bit "indicator field" marked by stars in the following 
extended format hex mask: XXXX XX** XXXX XXXX XXXX. This byte is the low half 
of the leading word of significant bits. The interpretation of the field is 
as given page 70 of Apple III Pascal, volume 2, subject to enhancements. 

4. When two quiet NANs are operands to the operations + , -, *, /, and REM, one 
or the other of the NANs is output. When the indicator fields differ, the NAN 
with the larger indicator field prevails; ties are broken arbitrarily. 

5. True to the standard, the sign of an output NAN is unspecified. 

6. Signaling NANs precipitate the invalid operation exception when they appear 
as operands. 

7. Underflow is tested before rounding. CHANGE: this may change depending on 
P754 deliberations in the late summer of '82 

8. Projective INF follows the same rules of signs as affine INF. The 
ABSOLUTELY ONLY differences between affine and projective modes ace: the 
UNORDERED-ness of projective INF in comparisons with finite numbers, and the 
invalid operation exception that arises from the sum of two projective INFs 
with the same sign. CHANGE: projective mode may be removed from P734 in late 
summer '82. 

9. Treatment of unnormalized extended numbers may differ between systems. 68K 
implementations will normalize all such, as is expected of the Motorola and 
Zilog chips. 6502 implementations may support the ANTIQUE warning mode in 
preliminary releases, though it may never be documented for general 
consumption. 

10. The bottom of the extended exponent range is as in the Motorola and Zilog 
implementations (as opposed to Intel). That is, there is no redundancy 
between the bottom two exponent values. 

11. The exponent bias in extended is hex 3FFF, which is used by Intel, Zilog, 
and Motorola. Motorola may insert a word of garbage between the sign/exp 
fields and the significant bits in order to have a 96-bit data type-. 

12. Comparisons return results according to local system convenience. 68K: 
return from the floating-point software with the CPU condition codes set 
appropriately for a conditional branch. 6502: for lack of a rich set of 
conditional branches, let the comparison operation be a family of boolean 
tests like "Is X <= Y?" The difference between the two systems should be 
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hidden well below the high-level language interfaces. 

13. Auxiliary functions: relegate functions like nextafterO to the system 
numerical library rather than putting them in the arithmetic engine. 

14. The data types specified by SANE are intl6, comp32, comp64, f32, f64, x80. 
68K systems will require int32 as well. 

15. Is the Pascal assignment: X :» Y; an arithmetic operation when both X 
and Y are variables of the same floating-point format? Or is a straight byte 
copy sufficient? This is really a language issue — one left dangling by the 
standard. The arithmetic units, if asked to perform a floating move between 
two floating entities of the same format, will perform a full-blown arithmetic 
operation. This will cause side effects if the floating value is a signaling 
NAN (invalid operation) or a denormalized number (underflow). 

16. Precision control is supported by 6502 and 68K packages, but it is 
available only through assembly language — it is intended only for SPECIAL 
applications anyway. Precision control implies range control, too. 

17. There is no "integer overflow” exception,. 

18. Traps? These are so system-dependent there is no hope for perfect 
consistency. So the issue is left as a local matter for each system. The 
question relevant to each floating-point engine is: "What Information will I 
be required to spew out in case of a trap?" 


f 
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K Design Philosophy 

The software package FP68K provides binary floating-point arithmetic 
according to the proposed IEEE standard P754. This arithmetic is in turn the 
basis for SANE, standard Apple nu'meric environment. The goal is software 
compatibility between the various Apple products supporting SANE. 

The arithmetic package is reasonably small and fast. Its interface is 
very simple. And it provides just those operations needed for applications 
software. Although developed specifically for Mac, the package is designed 
for use in Lisa, if desired. 

The following sequence of examples illustrates the SANE philosophy: 
Single operation: X + Y 

P754: Compute as if with unbounded range and precision, 
then coerce to destination format. 


Expression evaluation: Z :■ (X + Y)/(U + V); 

SANE: Compute all anonymous intermediate subexpressions 
to extended, then coerce to destination format. 




Loop: S :» 0.0; 

FOR I :» 1 TO N DO 

S :=* S + A[I]*B[I] ; 

VERY SANE: Wise programmer uses extended variable S to 
eliminate spurious over /under flows in the inner 
loop, and to reduce the final rounding error. 
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_2. Data Types 

The arithmetic supports the following data types. All are specified in 
SAME except for int32 and decimal. Int32 is included for convenience in 68K 
environments , where 32-bit integers are common. Through the decimal type the 
package provides the basis for the binary<->decimal conversions required by 
languages and the I/O system. 


intl6 

int32 

comp64 

f32 

f64 

x80 

decimal 


— 16-bit two 's-complement integer 

— 32-bit two 's-complement integer 

— 64-bit integer, with one reserved operand value 

— 32-bit single floating-point 

— 64-bit double floating-point 

— 80-bit extended floating-point 

— ascii digit string with integer sign and exponent 


3_. Arithmetic Operations 

These operations apply to floating-point operands: 

+ , “» *, /, SQRT, REMAINDER, COMPARE, 

ROUND TO INTEGER, TRUNCATE TO INTEGER, LOGB, SCALB, 

ABSOLUTE VALUE, NEGATE, COPYSIGN, NEXAFTER, CLASS 

Except for COMPARE, each produces a floating-point result. COMPARE sets the 
CPU flag bits according to the two operands. Besides its floating-point 
result, REMAINDER returns the sign and four least significant bits of its 
integer quotient in the CPU flags (a very useful trick for argument reduction 
in the transcendental functions). LOGB replaces a number by is unbiased 
exponent, in floating form; SCALB scales a number by an integer power of 2. 


4. Format Conversions 


intXX 

<— > 

extended 

comp 6 4 

<— > 

extended 

floating 

<— > 

floating (one operand must be extended) 

decimal 

<— > 

extended 


5_. Internal Architecture 

The package provides 2-address memory to memory arithmetic operations of 
the form 

<op> DST --> DST and 

SRC <op> DST --> DST 

where DST and SRC are the destination and source operands, respectively. The 
DST operand is always in the extended format. The conversions have the form: 
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SRC --> DST 

where at least one of SRC and DST - is a floating-point format. The package 
also provides a few support functions in connection with the floating-point 
error flags and modes. 

Extended format results may be coerced to the PRECISION and RANGE of the 
single or double formats, on an instruction by instruction basis. Then 
subsequent operations are able to take advantage of the trailing zeros to 
improve performance. This feature is provided to expedite special-purpose 
applications such as graphics and is not intended for general use. Only under 
certain circumstances will it actually obtain a speed advantage, rather than a 
DISADVANTAGE, since the package is built to do extended arithmetic. 

6_. External Access 

The package is re-entrant, position-independent code, which may be shared 
in multi-process environments. It is accessed through one entry point, 
labeled FP68K. Each user process has a static state area consisting of one 
word of mode bits and error flags, and a two-word halt vector. The package 
allows for different access to the state word in one-process (Mac) and 
multi-process (Lisa) environments. 

The package preserves all CPU registers across invokations, except that 
REMAINDER modifies DO. It modifies the CPU condition flags. Except for 
binary-decimal conversions, it uses little more stack area than is required to 
save the sixteen 32-bit CPU registers. Since the binary-decimal conversions 
themselves call the package (to perform multiplies and divides), they use 
about twice the space of the regular operations. 


7_. Calling Sequence 

A typical invokation of the package will consist of a sequence of four 
68K assembly instructions: 

PEA <source address> ;"Push Effective Address" 

PEA destination address> ;"Push Effective Address" 

MOVE.W <opword>, -(SP) ;"Push" operation word 

JSR FP68K ;"Call" the package 

(If FP68K resides in system memory, the JSR may be replaced by an A-line trap 
opcode.) Other calls will have more or fewer operand addresses to push onto 
the stack. The opword is the logical OR of two fields, given here in 
hexadecimal : 

"non-extended" operand format, bits 3800: 

0000 — x80 
0800 — f64 
1000 — f32 
1800 — ILLEGAL 
2000 — inti 6 
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2800 — int32 
3000 — comp64 
3800 — ILLEGAL 

arithmetic operation code, bits 001F: 

0000 — add 

0002 — subtract 

0004 — multiply 

0006 — divide 

0008 — compare 

000A — compare and signal invalid if UNORDERED 
000C — remainder 

000E — floating, intxx, comp64 — > extended convert 

0010 — — extended — — > intXX, comp64, floating convert 

0012 — square root 

0014 — round to integer in floating format 

0016 — truncate to integer in floating format 

0018 — scale by integer power of 2 
001 A — replace by unbiased exponent 
001C — classify the floating input 
00 IE — ILLEGAL 

0001 — put state word 

0003 — get state word 

0005 — put halt vector 

0007 — get halt vector 

0009 — decimal — > floating convert 
000B — floating — > decimal convert 
000D — negate 

000F — absolute value 

0011 — copy sign 

0013 — nextafter 

0015 — set exception 

0017 — procedure entry protocol 

0019 — procedure exit protocol 
001B — test exception 

00 ID and 00 IF are ILLEGAL 


8. Comparisons 

In this arithmetic, comparisons require some extra thought. The 
trichotomy rule of the real number system — that two numbers are related as 
LESS, EQUAL, or GREATER — is violated by the NANs, which compare UNORDERED 
with everything, even themselves. So it is necessary for floating-point 
comparisons to use the CPU condition codes in a way that seems surprising at 
first blush: 


RELATION 


EQUAL 

GREATER 

UNORDERED 


FLAGS: X N Z V C 


1 1 0 0 l 
0 0 10 0 
0 0 0 0 0 
0 0 0 l 0 
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This encoding leads to a very convenient mapping between the "floating-point 
conditional branches" and the CPU conditional branches. In the following 
table, the '?' refers to UNORDERED. The second column gives the name of the^ 
branch macro that provides the "floating branch" (see the Assembler Support 
document ) • 


BRANCH 

CONDITION 

MACRO NOTATION 

CPU BRAf 

S 



FBEQ 


BEQ 

< 



FBLT 


BCS 

< , ® 



• FBLE 


BLS 

> 



FBGT 


BGT 

>, * 



FBGE 


BGE 

?, < 



FBULT 


BLT 

?, <, 

a 


FBULE 


BLE 

> 



FBUGT 


BHI 

? > 

* » ' » 

a 


FBUGE 


BCC 



(unordered) 

FBU 


BVS 

<t -» 

> 

(ordered) 

FBO 


BVC 

7 < 

• 1 

> 

(not equal) 

FBNE 


BNE 

? f =■ 



FBUE 

BEQ 

/ BVS 

C, > 



FBLG 

BNE 

/ BVC 


Only in the last two instances, are two branches required. 

The variant comparison instruction, that signals the invalid operation 
exception if its operands are UNORDERED, is useful in high-level languages 
since P754 (and SANE) require that certain UNORDERED comparisons be marked 
invalid. 

Further discussion of the language issues of comparisons may be found in 
"Comparisons and Branching" by Jerome Coonen. 


9_. Binary-Decimal Conversions 

The package provides conversion functions intended to be used in 
conjunction with scanners and formatters peculiar to the user environment. 
For decimal to binary conversions, the input parameters are: 

address of Pascal decimal structure: 
record 

sgn : 0 . . 1 ; 
exp : integer; 
sig : string [20] 

end; 

address of target floating variable 
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The format (f32, f64, x80) of the target is given in the opword. For binary 
to decimal conversions, the input paramaters are: 

address of format structure: 
record 

style : (FloatDecimal , FixedDecimal) ; 

digits: integer 

end; 

address of source floating variable 

address of decimal structure: 

sign 

exponent 

ascii string of significant digits 

The interpretation of the latter format element depends on the style of the 
conversion. For fixed conversions, the digit count gives the number of 
fraction digits desired (which may be negative). For float conversions, the 
digit count gives the number of significant digits desired. 

Free format binary — > decimal conversions, which display numbers in the 
"nicest" format possible within given field width constraints, are supported 
in software, using the float style of conversion. Nice conversions are handy 
in applications like accounting spreadsheets where tables of numbers are 
displayed. See the "Binary-Decimal Conversion" document for details. The 
SANE interface gives details about the decimal format. 


10 . The State Area 

Each user of the package has three words of static floating-point state 
information. All accesses to the state should be made through the four state 
operations. The state consists of: 

modes and flags word: 

8000 — unused 

6000 — rounding direction: 

0000 — to nearest 
2000 — toward +INF 
4000 — toward -INF 
6000 -— toward zero (chop) 

1F00 — error flags, from high to low order: 

1000 — inexact result 
0800 — division by zero 
0400 — floating overflow 
0200 -— floating underflow 
0100 — invalid operation 


0080 — rounding of last result 
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OOOO — not rounded up in magnitude 
0080 — rounded up in magnitude 

0060 — precision control: 

0000 “ extended 
0020 — double 
0040 — single 
0060 — ILLEGAL 

001F — halt enables, correspond to error flags 
halt vector: 

32-bit address of alternate exit from package 


11. Halts 


When an error arises for which the corresponding halt is enabled , a trap 
is taken through the vector in the floating-point state area. The halt 
routine is called as a Pascal procedure of the form 


PROCEDURE MyHalt(VAR r: fpRegs; op3, op2, opl: fpPtr; opcode: integer); 

where 

TYPE 

fpRegs - RECORD BEGIN 

FPRCCR, { 68000 CCR register } 

FPRD0HI, { high word of register DO } 

FPRDOLO { low word of register DO } 


END; 

fpPtr a “Extended; 


but may be pointer to any type } 


The only way to return to the package from a halt is to initiate a new 
floating-point operation. There is no way to resume execution of the halted 
operation. 

The state— related operations never halt. The binary-decimal conversions 
do not halt, though the individual operations they employ (such as 
multiplication to form lO^N for some integer N) might halt. 






12 . Other P seudo-Machi nes 

The package is simple and general enough to be the basis for 
pseudo-machines with register architectures like the 68881 or the Z8070 or 
with an evaluation stack like the Intel 8087 . What is needed is simply the 
mechanism to compute addresses in the register file or stack (and check for 
internal consistency), and the set of functions required to manipulate that 
isolated data file (e.g. duplicate the top stack element, negate a register). 


13 . Arithmetic Abuse 

The package is designed to be as robust as possible but it is not 
bullet-proof, since it is specified to modify the stack. If the user passes 
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illegal addresses, a memory fault may arise when the package attempts to 
access the operands* And if the user passes the wrong number of address 
operands, then in general the stack will be irreparably damaged. Operation is 
undefined if ILLEGAL values are used in the opword parameter. 


14 . Size and Performance 

FP68K is about 4000 bytes long. On a 4mhz system it executes the 
simplest arithmetic operations in about 0.4ms and requires just over 1.0ms for 
a full extended multiply. Divide and square root are longer yet. 

Comparative timings show that, for double format operations, FP68K is 
just faster than the AMD 9512 on Lisa and is about twice twice as fast as the 
Motorola 68341 code. For single format operations, FP68K is about half as 
fast as the Lisa single-only package, which is just slower than the 9512. 


15 . Floating-Point at _a Glance 

Figure 1 at the end of this document illustrates the basic control of 
flow in the execution of the floating-point package. The figure is followed 
by a list of observations on the behavior of the package, and of IEEE 
arithmetic in general. 
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1. The package has a single entry point* 

2. The package has two exit points, one for normal subroutine returns and one 
for halts through a vector* 

3* Three classes of operations are distinguished: arithmetic operations, 

1 binary-decimal conversions, and accesses to the state word and halt vector. 

4. The not-a-number symbols, NANs, are detected at the start of each 
operation. Of them, signaling NANs are the most virulent; they always trigger 
the invalid operation exception* Quiet NANs propagate through operations; a 
precedence rule determines which is output if two are input. 

5* Invalid operations always result in a quiet NAN output* In the case of the 
discrete types INT16, INT32, C0MP64, the output value is all zero bits except 
for a leading one bit (that is, 100000* ••)• Floating-point NANs contain an 
error code to indicate their origin (such as 01 for square root of a negative 
number ) • 

6* When the input operands are unpacked, the special cases 0, FNZ (finite 
nonzero number), and INF (infinity) are detected. This expedites special 
cases such as 

+INF + FNZ — > +INF 

7. When 0 or INF results from a trivial operation like the example above, no 
further processing is required before the value is packed* All nontrivial 
floating-point results are subject to precision and range coercion to assure 
that they fit in the intended destination. 

8* Integer results are subject to coercion to detect overflow* 

9. Floating-point NAN results are coerced by chopping them to the precision of 
the destination, and checking that a legitimate value results* 

10. Comparisons require special care, since they produce no results but rather 
modify the CPU condition— code register. Comparisons, even when NANs are 
involved, must bypass the coercion steps. 
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Introduction 


This is a brief guide to the program FP68K, a software implementation of 
proposed IEEE standard P754 (Draft 10.0) for biliary floating-point arithmetic. 
This guide is intended to aid a programmer wishing to understand the workings 
of FP68K. 


The code 

The software is in the assembly language df the Motorola MC68000, 
following the Apple "TLA" syntax of the Lisa assembler. FP68K is 
non-self -modifying , position-independent code. It has no local data area, 
that is it uses dynamically allocated stack area for all of its temporaries. 
FP68K is one large subroutine whose single entry point has the name FP68K. 


The code is separated into the functionally distinct files: 


FPDR1VER. TEXT 

FPEQUS.TEXT 

FPC0NTR0L . TEXT 

FPUNP ACK . TEXT 

FP ADD. TEXT 

FPMUL.TEXT 

FPDIV.TEXT 

FPREM.TEXT 

FPCMP.TEXT 

FPSQRT.TEXT 

FPCVT.TEXT 

FPSLOG.TEXT 

FPNANS.TEXT 

FPCOERCE.TEXT 

FPP ACK. TEXT 

FPODDS.TEXT 

FBD2B.TEXT 

FBB2D.TEXT 

FBPTEN.TEXT 


-- "includes" the other files... 

— defines set of named constants 

— organizes the flow of control 

-- unpack input operands to intermediate format 

— add and subtract 

— multiply 

— divide 

— remainde r 

— compare 

-- square root 

floating < — > floating, integer conversions 

— logb, scalb, and class appendix functions 

— handle "Not A Number” symbols 

— post-normalize, round, check over/underflow... 

— pack result to storage format 

— non-arithmetic operations 

— decimal — > binary conversion 

— binary — > decimal conversion 

— computes 10~N for nonnegative integer N 


As noted, FPDRIVER.TEXT is a short file which simply includes the other files 
between the ".PROC" header and ".END" trailer. 






Assembling FF68K 

Assemble the file FPDRIVER.OBJ to produce the FP68K object file. 

The one system dependency of FP68K is its access of the floating-point 
state area, as discussed in the "System Implementor’s Guide". Near the top of 
FPCONTROL.TEXT is the code which pulls the address of the the 3-word state 
area into register AO. This code will typically require modification when 
FP68K is moved to a new system. The well-marked comment within FPCONTROL.TEXT 
indicates the different access schemes systems might use. If the state area 
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is to be located using a constant defined in a public "include" file, then 
that file should be included within FPDRIVER. TEXT . See the comment there for 
details. 

Ocher than its access to the state area, FP68K is intended to 
system-independent and should not be tailored recklessly. 


Control flow 

There are three fundamentally distinct classes of operations performed by 
FP68K: basic arithmetic, binary-decimal conversions, and manipulations of the 
floating-point state area. The last of these, namely reading and writing the 
state word and the halt vector, is trivial and needs no explanation beyond the 
simple code contained in FPODDS.TEXT. 

The basic arithmetic operations are illustrated in the flow chart at the 
end of this note. The chart is marked to distinguish the function of the 
various files listed above. 

The binary-decimal conversions are quite different from the basic 
operations, and are not described by the basic flow chart. The conversions 
might better be thought of as subroutines which have been implemented within 
FP68K as a matter of architectural convenience. The conversions invoke FP68K 
itself to perform various basic operations like multiply and divide. The 
binary-decimal algorithms are described in considerable detail in the attached 
paper "Accurate, Yet Economical Binary-Decimal Conversions" by J. Coonen. 


Exponent calculations 

FP68K manipulates exponents in a way that might seem surprising at first 
glance. The P754 extended format, on which all FP63K arithmetic is based, has 
a 1-bit sign, 15-bit exponent, and a 64-bit significand. However, the actual 
exponent range is not 0 to 32767 (biased by 16383) as the 15-bit exponent 
field would suggest. Rather, it is -63 to 32767 because of the presence of 
tiny denormalized numbers; this is "just a little bit" beyond the stated 
15-bit range. (See the attached paper "Underflow and the Denormalized 
Numbers" by J. Coonen for a discussion of tiny values in P754 arithmetic.) 

Because the operations multiply and divide require the addition and 
subtraction, respectively, of operand exponents in forming their intermediate 
results, the implementor typically expects to have one extra exponent bit for 
intermediate calculations. Thus for P754 extended format calculations, there 
is need for "just a little bit" beyond 16 exponent bits. This elusive 17-th 
bit is discussed in yet another attached paper, "Are 17 Exponent Bits Too 
Many?" It is shown there that 16 bits suffice, if care is taken to perform 
some extra tests in the right places. 

On the 68000 it turns out to be convenient to perform exponent 
calculations in the ADDRESS REGISTERS -— with a full 32 bits. The address 
registers provide just the right functionality: add, subtract, and compare. 
And since floating-point arithmetic is computation-intensive on a small data 
set, only a few of the address registers are actually needed for addresses. 
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Finally, 16-bit constants like the exponent bias may be added into the 32-bit 
exponents with a 2— word instruction, since for "address" calculations the 
constant is first sign— extended out to a full 32 bits. 


Bit field encodings 

This section describes the various bit fields used by FP68K. Some of 
them, like the opcode and the state word, are visible to programs invoking 
FP68K. Others, like the rounding and sign bits, are local to FP68K. 

The OPCODE is the last word pushed on the stack before calling FP68K. It 
is composed of the fields: 

3800 — "non-extended" operand format: 

0000 — x80 
0800 — f64 
1000 -- f32 
1800 — ILLEGAL 
2000 — intl6 
2800 — int32 
3000 — comp64 
3800 — ILLEGAL 

07E0 — must be zero 

001F — operation code: 

0000 — add 

0002 — subtract 

0004 — multiply 

0006 — divide 

0008 — compare 

000A -— compare (invalid if UNORDERED) 

000C — remainder 

0O0E — — x80, f64, f 32 , intl6, int32, comp64 — > x80 

0010 — x80 — > x80, f64 , f32, intl6, int32, comp64 

0012 — square root (in x80) 

0014 — round to integer (in x80) 

0016 — truncate to integer (in x80) 

0018 — scale by unbiased power of 2 
001 A — replace by unbiased exponent 
00 1C — classify the fldating input 
00 IE — ILLEGAL 

0001 — put state word 

0003 — get state word 

0005 — put halt vector 

0007 — get halt vector 

0009 — decimal — > floating convert 
000B — floating — > decimal convert 
000D — negate 

000F -— absolute value 

0011 — copy sign - 

0013 — nextafter 
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0015 — set exception 

0017 — procedure entry protocol 

0019 — procedure exit protocol 

001B — test exception 

00 ID and 00 IF are ILLEGAL 


The STATE word is static data that perseveres across calls to FP68K. As 
such, it must live in an area outside FP68K, defined by the host system. 
Typically the state word (and the halt vector, which is a 32-bit address) will 
live in the system's "per-process data area", perhaps a fixed location in 
memory or a fixed offset from some reserved address register. Although the 
STATE word is directly available to the programmer, typical access will be 
through an intermediate layer of software (available, say, in a Pascal unit) 
that insulates the programmer from the details of the actual bit encodings. 

The STATE word is composed of the fields: 

8000 -- unused 

6000 -— rounding mode : 

0000 — to nearest 
2000 -- toward +INF 
4000 -- toward -INF 
6000 -- toward 0 (chop) 

1F00 — error flags: 

1000 — inexact result 
0800 -— division by zero 
0400 -- floating overflow 
0200 — floating underflow 
0100 — invalid operation 

0080 — rounding of last result 

0000 — not rounded up in magnitude 
0080 — rounded up in magnitude 

0060 -- precision control: 

0000 -— extended 
0020 -- double 
0040 — - single 
0060 — ILLEGAL 

001F — exception halt enables: 

(correspond to error flags above) 


After preliminary decoding in FPCONTROL. TEXT , the OPCODE is expanded out 
into the following 16— bit form: 

8000 — nonzero iff result has single precision and range 

4000 — nonzero iff result has double precision and range 

3800 — source operand format : 
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(same encoding as in OPCODE) 

0700 — destination operand format: 

(same encoding as in OPCODE) 

0080 — — nonzero iff destination operand is input 

0040 — nonzero iff source operand is input 

0020 — nonzero iff destination operand is output 

001E — operation code: 

(same encoding as in OPCODE but with low bit 0) 
0001 — nonzero iff two-address operation 


The ROUND BITS, known as "guard", "round", and "sticky" in documentation 
about P754, are kept in a 16-bit word. Roughly speaking, the guard and round 
bits are the two bits beyond the least significant bit of the intermediate 
result, and the sticky bit is the logical Or of all bits thereafter. The 
sticky bit is necessary to implement the rounding modes of P754. The ROUND 
BITS are kept as: 

8000 — guard bit 

4000 — round bit 

3F00 — 6 extra round bits 

00FF — sticky bits 

The reason for keeping an entire byte of sticky bits lies in the 68000 
instruction set. The archetype operation involving the sticky bit is the 
right— shift. Any time a bit is shifted off the low end of the sticky "byte , 
it must be logically Or— ed back into sticky. This is done with the 68000 
"SCS" instruction, which sets a given byte to all Is if the carry bit is set, 
and clears the byte to 0 otherwise. Typically, a bit is shifted off to the 
right, it is SCS-ed into an auxiliary byte, and that byte is Or-ed into the 
sticky byte. Although this is the typical use of the sticky byte, the 
programmer should not assume that the sticky byte is always either all 0s or 
all Is. Sometimes, such as in the right shift after a carry-out in ADD/SUB, 
the logical Or will be omitted since it is known that if a l was shifted out 
of the sticky byte there will necessarily be another 1 left in sticky. 


The operands' SIGNS are kept together in a byte as follows: 

80 — source operand sign 

40 — destination operand sign 

20 — Exclusive Or of the two operands ' signs 

IF — unused, but not necessarily zero 

If there is just one input operand, its sign is in the high order bit. The 
Exclusive Or is computed just once, at the start of every arithmetic 
operation. Not only is it required for many common operations (+, -, *, /, 
REM, CMP), but it is costly in time and space because of the inefficacy of the 
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68000 bit instructions, so it is worthwhile to implement the code sequence 
just once* 


The CCR (condition code register) bits of the 68000 are modified by every 
arithmetic operation, though only the compare instructions leave them in a 
well defined state. A CCR word is maintained by FP68K: 

FFE0 — unused, forced to 0 
0010 — X =■ Extend 
0008 — N =* Negative 
0004 — Z =* Zero 
0002 — V = "Overflow 
0001 — C * Carry 

The compare operations encode their results as follows: 

RELATION FLAGS: X N Z V C 


LESS 11001 
EQUAL 00100 
GREATER 00000 
UNORDERED 00010 

See the FP68K programmer's manual for the software applications of the CCR 
field. 


Register usage 

The key to the speed (such as it is) and compactness of FP68K is that its 
entire working data set may be held in the 68000 register file. Immediately 
upon entry, FP68K saves registers D0-D7, A0-A4 on the stack. Then the 
registers are loaded up as the operation proceeds. Several of the registers 
have a meaning that perseveres across nearly the entire instruction. The 
following list gives a rough idea of register usage: 

D7 hi — CCR word 
D7 lo — round bits 
D6 hi — opcode word 

D6 lo — error byte (hi) and sign byte (lo) 

D5 — low 32 source (later result) significant bits 
D4 — high 32 source (later result) sig nificant biCg 
D3-D0 — scratch area 


7 — SP * stack pointer 

A6 — stack link pointer 

A5 — Mac globals poionter 

A4 — source (later result) exponent 

A3 — destination exponent 

A2 — low 32 destination significant bits 

A1 — high 32 destination significant bits 
AO — pointer to 3-word state area 
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Of course, the arithmetic operations may be viewed as transformations of the 
register file. Following this view, a set of register maps are included at 
the end of this note. They are keyed to MILESTONES marked in the source code. 
The maps indicate register dependencies, and as such should aid in any 
modification of FP68K. Some maps simply indicate the state of the register 
file at a given point, and some indicate register use in a routine, such as 
the widely used right-shift procedure RTSHIFT. 

For convenience the maps are printed on onion skin paper; a reference 
sheet slips under the map to fill in the register mask. 

Register DO is modified by the REMAINDER operation., in which case a 
partial integer quotient is returned in DO.W. 


Stack usas 


When called, FP68K assumes that the stack has the form: 


ADDRESS 3 — used for decimal format code only 
ADDRESS 2 — source pointer, if any 
ADDRESS 1 -- destination pointer 
OPCODE — one word 
RETURN ADDRESS 




The number of address operands depends on the operation. FP68K then allocates 
3 more stack words: 


COUNT — number of bytes in original call frame 
HALT ADDRESS 

This frame is used if a halt is taken. The COUNT field allows the halt 
handler to simply pop the original operands and return, if desired. 

Above this frame, FP68K pushes registers DO-7 , AO-6. In the progress of 
an operation, up to 6 more words of stack may be used. The total stack usage, 
after the call, is then up to 3 + 32 + 6 3 41 words. The binary-decimal 
conversions may use twice this much since they invoke FP68K to perform basic ^ 

arithmetic operations. 
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ABSTRACT 

Packages are sets of data structures and routines that are stored as 
resources and brought into memory only when needed* There's a package 
for presenting the standard user interface when a file is to be saved or 
opened, and others for doing more specialized operations such as 
floating-point arithmetic* This manual describes packages and the 
Package Manager, the part of the Macintosh User Interface Toolbox that 
provides access to packages. 


Summary of significant changes and additions since last draft: 

- The documentation of the International Utilities Package and the 
Binary-Decimal Conversion Package has been added. 

- There’s a new feature in the Standard File Package routine 
SFGetFile, whereby the user can select a file name by pressing a 
key. 
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ABOUT THIS MANUAL 


This manual describes packages and Che Package Manager* The Macintosh 
packages include one for presenting the standard user interface when a 
file is to be saved or opened, and others for doing more specialzed 
operations such as floating-point arithmetic* The Package Manager is 
the part of the Macintosh User Interface Toolbox that provides access 
to packages* *** Eventually, this will become part of the 
comprehensive Inside Macintosh manual* *** 

You should already be familiar with the Macintosh User Interface 
Guidelines, Lisa Pascal, the Macintosh Operating System's Memory 
Manager, and the Resource Manager. Using the various packages may 
require that you be familiar with other. parts of the Toolbox and 
Operating System as well. 

This manual is intended to serve the needs of both Pascal and assembly- 
language programmers. Information of interest to assembly-language 
programmers only is isolated and labeled so that Pascal programmers can 
conveniently skip it. 

The manual begins with a discussion of the Package Manager and packages 
in general. This is followed by a series of sections on the individual 
packages. You'll only need to read the sections about the packages 
that interest you. Each section describes the package briefly, tells 
how its routines fit into the flow of your application program, and 
then gives detailed descriptions of the package's routines. 

Finally, there are summaries of the Package Manager and the individual 
packages, for quick reference, followed by a glossary of terms used in 
this manual. 
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THE PACKAGE MANAGER 

The Package Manager is the part of the Macintosh User Interface Toolbox 
that enables you to access packages . Packages are sets of data 
structures and routines that are stored as resources and brought into 
memory only when needed. They serve as extensions to the Macintosh 
Operating System and User Interface Toolbox , for the most part 
performing less common operations. 

The Macintosh packages, which are stored in the system resource file, 
include the following: 

- The Standard File Package, for presenting the standard user 
interface when a file is to be saved or opened. 

- The Disk Initialization Package, for initializing and naming new 
disks* This package is called by the Standard File Package; 
you 1 11 only need to call it in nonstandard situations* 

- The International Utilities Package, for accessing country- 
dependent information such as the formats for numbers, currency, 
dates, and times* 


- The Binary-Decimal Conversion Package, for converting integers to 
decimal strings and vice versa* 

- The Floating-Point Arithmetic and Transcendental Functions 
Packages* *** These packages, which occupy a total of about 8*5K 
bytes, will be documented in a future draft of this manual* *** 

Packages have the resource type 'PACK 1 and the following resource IDs: 


CONST dsklnit 

at 

2; 

{Disk Initialization} 


stdFile 

m 

3; 

{Standard File} 


f lPoint 

m 


{Floating-Point Arithmetic} 


trFunc 

m 

5; 

{Transcendental Functions} 


intUtil 

m 

6; 

{International Utilities} 


bdConv 

- 

7; 

{Binary-Decimal Conversion} 



Assembly— language note : All macros for calling the routines in 

a particular package expand to invoke one macro, PackN, where 

is the resource ID of the package. The package determines which 
routine to execute from the routine selector , an integer that s 
passed to it on the stack* For example, the routine selector 
for the Standard File Package procedure SFPutFile Is 1, so 

invoking the macro SFPutFile pushes 1 onto the stack and 

invokes Pack3* 


There are two Package Manager routines that you can call directly from 
Pascal: one that lets you access a specified package and one that lets 
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you access all packages. The latter will already have been called when 
your application starts up, so normally you won't ever have to call the 
Package Manager yourself. Its procedures are described below for 
advanced programmers who may want to use them In unusual situations. 


PROCEDURE InitPack (packID: INTEGER); 

InltPack enables you to use the package specified by packID, which is 
the package's resource ID. (It gets a handle that will be used later 
to read the package into memory.) 


PROCEDURE InitAllPacks; 

Ini tAll Packs enables you to use all Macintosh packages (as though 
InitPack were called for each one). It will already have been called 
when your application starts up. 
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THE INTERNATIONAL UTILITIES PACKAGE 


The International Utilities Package contains routines and data types 
that enable you to make your Macintosh application country-independent* 
Routines are provided for formatting dates and times and comparing 
strings in a way that's appropriate to the country where your 
application is being used* There's also a routine for testing whether 
to use the metric system of measurement* These routines access 
country-dependent information (stored in a resource file) that also 
tells how to format numbers and currency; you can access this 
information yourself for your own routines that may require it* 

*** In the Inside Macintosh manual , the documentation of this package 
will be at the end of the volume that describes the User Interface 
Toolbox. *** 

You should already be familiar with the Resource Manager, the Package 
Manager, and packages in general. 


International Resources 


Country-dependent information is kept in the system resource file in 
two resources of type 'INTL', with the resource IDs 0 and 1: 

- International resource 0 contains the format for numbers, 
currency, and time, a short date format, and an indication of 
whether to use the metric system. 

- International resource 1 contains a longer format for dates 
(spelling out the month and possibly the day of the week, with or 
without abbreviation) and a routine for localizing string 
comparison. 

The system resource file released in each country contains the standard 
international resources for that country. Figure 1-1 illustrates the 
standard formats for the United States, Great Britain, Italy, Germany, 
and France. 
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United 

States 

Great 

Britain 

Italy 

Germany 

France 

Numbers 1,234.56 

List separator ; 

1,234.56 

# 

1.234,56 

• 

J 

1.234,56 

• 

J 

1 234.56 

• 

1 

Currency 

la 23 

(10.45) 

$345.00 

£a23 

(£0.45) 

£345 

L 423 
L-445 

L 345 

423 DM 
-445 DM 
325*00 DM 

423 F 
-445 F 
325 F 

Time 

9(05 AM 
11:30 AM 
11:20 PM 
11:20:09 PM 

09(05 

11:30 

23(20 

23(20(00 

9(05 

11:30 

23(20 

23:2009 

9.05 Uhr 
11.30 Uhr 
23.20 Uhr 
23.2009 Uhr 

9:05 

11:30 

23(20 

23:2009 

Short date 

12/22/84 

2/ 1/04 

22/12/1984 

01/02/1984 

22-12-1984 

1-02-1984 

22.12.1984 

1.02.1984 

22.12.84 

1.02.84 



Unabbreviated 

Abbreviated 

Long date 

Uhited States 
Great Britain 
Italy 

Germany 

France 

Wednesday, February 1, 1984 We4 Feb 1, 1984 

Wednesday, February 1, 1984 Wed, Feb 1, 1984 

mercoledi 1 Febbraio 1984 mer 1 Feb 1984 

Mittwoct\ 1. Februar 1984 Mit 1. Feb 1984 

Mercredi 1 fevrier 1984 Mer 1 fev 1984 


Figure 1-1. Standard International Formats 

The routines in the International Utilities Package use the information 
in these resources; for example, the routines for formatting dates and 
times yield strings that look like those shown in Figure 1-1. Routines 
in other packages, in desk accessories, and in ROM also access the 
international resources when necessary, as should your own routines if 
they need such information* 

In some cases it may be appropriate to store either or both of the 
international resources in the application's or document's resource 
file, to override those in the system resource file* For example, 
suppose an application creates documents containing currency amounts 
and gets the currency format from international resource 0* Documents 
created by such an application should have their own copy of the 
international resource 0 that was used to create them, so that the unit 
of currency will be the same if the document is displayed on a 
Macintosh configured for another country* 

Information about the exact components and structure of each 
international resource follows here; you can skip this if you intend 
only to call the formatting routines in the International Utilities 
Package and won't access the resources directly yourself* 
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International Resource 0 


The International Utilities Package contains the following data types 
for accessing international resource 0: 


TYPE Intl0Hndl 
Intl0Ptr 
Intl0Rec 


“Intl0Ptr; *** Following "Int" is the letter "1" *** 
~Intl0Rec; 


PACKED RECORD 



decimalPt : 

CHAR; (decimal point character} 


thousSep: 

CHAR; (thousands separator} 


listSep: 

CHAR; (list separator} 


currSyml : 

CHAR; (currency symbol} 


currSym2: 

CHAR; 


currSym3 : 

CHAR; 


currFmt : 

Byte; (currency formht} 


dateOrder: 

Byte; {order of short date elements} 

shortDateFmt : 

Byte; (short date format} 


dateSep: 

CHAR; (date separator} 


timeCycle: 

Byte; (0 if 24-hour cycle, 255 if 

12-hour} 

timeFmt: 

Byte; (time format} 


mornStr : 

PACKED ARRAY [ 1 • • 4 ] OF CHAR; 



(trailing string for first 12-hour cycle} 

eveStr : 

PACKED ARRAY[ 1.. 4] OF CHAR; 



(trailing string for last 12-hour cycle} 

time Sep: 

CHAR; (time separator} 


timelSuf f : 

CHAR; (trailing string for 24-hour 

cycle } 

time2Suff : 

CHAR; 


time3Suf f : 

CHAR; 


time4Suf f : 

CHAR; 


time5Suf f : 

CHAR; 


time6Suf f : 

CHAR; 


time7 Suf f : 

CHAR; 


time8Suff : 

CHAR; 


metricSys : 

Byte; (255 if metric, 0 if not} 


int!0Vers : 

INTEGER (version information} 



END; 


(note) 

A NUL character (ASCII code 0) in a field of type CHAR 
means there's no such character* The currency symbol and 
the trailing string for the 24-hour cycle are separated 
into individual CHAR fields because of Pascal packing 
conventions. All strings include any required spaces. 


The decimalPt, thousSep, and listSep fields define the number format. 
The thousands separator is the character that separates every three 
digits to the left of the decimal point. The list separator is the 
character that separates numbers, as when a list of numbers is entered 
by the user; it must be different from the decimal point character. If 
it's the same as the thousands separator, the user must not include the 
latter in entered numbers. 
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CurrSyml through currSym3 define the currency symbol (only one 
character for the United States and Great Britain, but two for France 
and three for Italy and Germany)* CurrFmt determines the rest of the 
currency format, as shown in Figure 1-2* The decimal point character 
and thousands separator for currency are the same as in the number 
format* 


7 6 5 4 3 0 

| | | 1 | not used | 


L 


1 if currency symbol leads, 0 if it trails 
1 if minus sign for negative, 0 if parentheses 
1 if trailing decimal ze ro es , 0 if not 
1 if leading integer zero, 0 if not 

Figure 1-2* CurrFmt Field 


Example of affect 

Ills 

If OS 

$3.00 

3 F 

-0^45 F 

($0.45) 

$325.00 

325 F 

$0123 

$.23 

be used to 

set or 


test the bits in the currFmt field: 


CONST currSymLead - 16; {set 
currNegSym ■ 32; {set 
currTrailingZ - 64; {set 
currLeadingZ ■ 128; {set 


if currency symbol leads} 
if minus sign for negative} 
if trailing decimal zeroes} 
if leading integer zero} 


(note) 

You can also apply the currency format's leading- and 
tralling-zero indicators to the number format if desired. 

The dateOrder, shortDateFmt , and dateSep fields define the short date 
format* DateOrder indicates the order of the day, month, and year, 
with one of the following values: 


CONST mdy - 0; 
dmy « 1 ; 
ymd » 2; 


{month day year} 
{day month year} 
{year month day} 


ShortDateFmt determines whether to show leading zeroes in day and month 
numbers and whether to show the century, as illustrated in Figure 1-3* 
DateSep is the character that separates the different parts of the 
date. 


7 6 5 4 0 

1 | | 1 not used 


1 

1 

1 


if leading zero for day, 0 if not 
if leading zero for montft 0 if not 
if century include^ 0 if not 


Example of effect 
If 1: If Os 

12/02/84 12/ 2/84 

01/31/84 1/31/84 

22.12.1984 22.12.84 


Figure 1-3* ShortDateFmt Field 
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To set or test the bits in the shortDateFmt field, you can use the 
following predefined constants as masks: 

CONST dayLeadlngZ - 32; {set if leading zero for day} 

mntLeadlngZ - 64; {set if leading zero for month} 

century - 128; {set if century included} 

The next several fields define the time format: the cycle (12 or 24 
hours); whether to show leading zeroes (tlmeFmt, as shown in Figure 
1-4); a string to follow the time (two for 12-hour cycle, one for 
24-hour); and the time separator character* 

7 6 5 4 0 

| | | | not used ~\ 

1 if leading zero for seco n ds , 0 if not 
1 if leading zero for minutes, 0 if not 
1 if leading zero for hours, 0 if not 

Figure 1-4* TlmeFmt Field 

The following masks are available for setting or testing bits in the 
tlmeFmt field: 

CONST secLeadingZ - 32; {set if leading zero for seconds} 

minLeadingZ - 64; {set if leading zero for minutes} 

hrLeadingZ - 128; {set if leading zero for hours} 

MetricSys indicates whether to use the metric system* The last field, 
intl0Vers, contains a version number in its low-order byte and one of 
the following constants in its high-order byte: 

CONST verUS - 0; 

ver France ■ 1 ; 
verBritain ■ 2; 
ver Germany - 3; 
verltaly ■ 4; 



Example of effect 
If 1: If ft 

11:16:05 11:1ft 5 

lOtOS 1ft 5 

09:15 9:15 


International Resource 1 


The International Utilities Package contains the following data types 
for accessing international resource 1 : 
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TYPE IntllHndl 
IntllPtr 
IntllRec 


■“IntllPtr; *** Following "Int" Is the letter "l" *** 
■“IntllRec; *** Following "Inti" Is the number "1" *** 
PACKED RECORD 


dsys: 

months : 

suppress Day : 

longDateFmt : 

dayleading0 : 

abbrLen: 

st0: 

stl: 

st2: 

8t3: 

st4: 

intllVers : 
localRtn: 


END; 


ARRAY [ l • .7 ] OF STRING [IS]; {day names } 
ARRAY [1.. 12] OF STRING! 15]; {month names] 
Byte; {0 for day name, 255 for none] 
Byte; {order of long date elements] 
Byte; {255 for leading 0 in day number] 
Byte; {length for abbreviating names] 
PACKED ARRAY [ 1 • . 4 ] OF CHAR; {strings ] 
PACKED ARRAY[1..4] OF CHAR; { for ] 

PACKED ARRAY[1..4] OF CHAR; { long ] 
PACKED ARRAY[ 1.. 4] OF CHAR; { date ] 
PACKED ARRAY [ 1 . • 4 ] OF CHAR; { format] 
INTEGER; {version information] 

INTEGER {routine for localizing string } 
{ comparison; actually may be } 

{ longer than one integer] 


All fields except the last two determine the long date format* The day 
names in the days array are ordered from Sunday to Saturday* (The 
month names are of course ordered from January to December*) As shorn 
below, the longDateFmt field determines the order of the various parts 
of the date* St0 through st4 are strings (usually punctuation) that 
appear in the date. 


longDateFmt Long date format 

0 st0 day name stl day st2 month st3 year st4 

255 8t0 day name stl month st2 day st3 year st4 

See Figure 1-5 for examples of how the International Utilities Package 
formats dates based on these fields* The examples assume that the 
suppressDay and dayLeading0 fields contain 0. A suppress Day value of 


255 causes the day 
of 255 causes a 0 

name and stl to be 
to appear before day 

omitted, and a dayLeading value 
numbers less than 10. 

longDateFmt 

stO 

Stl 

st2 

st3 

st4 

Sample result 

0 

H 

1 1 

I 

1 1 

• 

1 9 

II 

Mittvocty Z Februar 1984 

255 

II 

1 1 
» 

1 1 

1 1 
» 

II 

Wednesday, February 1, 1984 


Figure 1-5* Long Date Formats 


AbbrLen is the number of characters to which month and day names should 
be abbreviated when abbreviation is desired. 


The IntllVers field contains version information with the same format 
as the intl0Vers field of international resource 0* 

LocalRtn contains a routine that localizes the built-in character 
ordering (as described below under "International String Comparison"). 
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International String Comparison 

The International Utilities Package lets you compare strings in a way 
that accounts for diacritical marks and other special characters. The 
sort order built into the package may be localized through a routine 
stored in internatiomal resource 1. 

The sort order is determined by a ranking of the entire Macintosh 
character set. The ranking can be thought of as a two-dimensional 
table. Each row of the table is a class of characters such .as all A's 
(uppercase and lowercase, with and without diacritical marks). The 
characters are ordered within each row, but this ordering is secondary 
to the order of the rows themselves. For example, given that the rows 
for letters are ordered alphabetically, the following are all true 
under this scheme: 

'A' < 'a' 
and 'Ab' < 'ab' 
but 'Ac' > 'ab' 

Even though 'A' < 'a' within the A row, 'Ac' > 'ab' because the order 
'c' > 'b' takes precedence over the secondary ordering of the 'a' and 
the 'A'. In effect, the secondary ordering is ignored unless the 
comparison based on the primary ordering yields equality. 

(note) 

The Pascal relational operators are used here for 
convenience only. String comparison in Pascal yields 
very different results, since it simply follows the 
ordering of the characters' ASCII codes. 

When the strings being compared are of different lengths, each 
character in the longer string that doesn't correspond to a character 
in the shorter one compares "greater"; thus 'a' < 'ab'. This takes 
precedence over secondary ordering, so 'a' < 'Ab' even though 
'A' < 'a*. 

Besides letting you compare strings as described above, the 
International Utilities Package includes a routine that compares 
strings for equality without regard for secondary ordering. The effect 
on comparing letters, for example, is that diacritical marks are 
ignored and uppercase and lowercase are not distinguished. 

Figure 1-6 on the following page shows the two-dimensional ordering of 
the character set (from least to greatest as you read from top to 
bottom or left to right). The numbers on the left are ASCII codes 
corresponding to each row; ellipses (...) designate sequences of rows 
of just one character. Some codes do not correspond to rows (such as 
$61 through $7 A, because lowercase letters are included in with their 
uppercase equivalents). See the Toolbox Event Manager manual for a 
table showing all the characters and their ASCII codes. 
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$00 

ASCII NUL 

e e e 

SIF 

ASCII US 


$20 

space nonbn 

$21 

1 



$22 

•1 

« » 

m 

$23 

# 



$24 

$ 



$25 

% 



$26 

& 



$2? 

• 

* 9 


$20 

( 



$40 

<3> 

% V 


$41 

A 

A A 

i 

$42 

B 

b 


$43 

C 

Q c 

9 

$45 

E 

£ e 

£ 

$49 

1 

i 1 

1 

$4E 

N 

fi n 

PI 

$4F 

0 

0 0 

0 

$55 

U 

0 u 

u 

$59 

Y 

y y 


$5B 

[ 



$5C 

\ 



$5D 

] 



$5E 

A 



$5F 




$60 

% 



$7B 

{ 



$7C 

1 



$70 

} 



$7E 

0*0 



$7F 

ASCII DEL 

$A0 

t 



$AD 

* 



$AE 

£ 

® CE 

$B0 

oo 



$BD 

Q 



$C0 

i 



$C9 

• •• 



$D0 

- 



$D2 

— 



$D6 

«+• 



$D7 

o 




A&a6 6£aS& 


* 

T 

o 

% 

u 


e 

i 

6 

D 


6 

u 


a 660 


letters not shown 
like "B b" 


CB (see remarks about ligatures) 


Figure 1-6. International Character Ordering 
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Characters combining two letters, as In the $AE row,' are called 
ligatures . As shown in Figure 1-7 , they're actually expanded to the 
corresponding two letters, in the following sense: 

- Primary ordering: The ligature is equal to the two-character 
sequence. 

- Secondary ordering: The ligature is greater than the 
two-character sequence. 

Standard: 


> 

m 

rh 

ae 

as 

OE CE 

oe 

oe 

Germany. 

AE A 

£ 

ae a ae 

OE 0 

CE 

oe 6 ae 

SS & 

UE 0 

ue 

u 


Figure 1-7 . Ordering for Special Characters 

Ligatures are ordered somewhat differently in Germany to accommodate 
umlauted characters (see Figure 1-7). This is accomplished by means of 
the routine in international resource 1 for localizing the built-in 
character ordering. In the system resource file for Germany, this 
routine expands umlauted characters to the corresponding two letters 
(for example, "AE" for A-umlaut). The secondary ordering places the 
umlauted character between the two-character sequence and the ligature, 
if any. Likewise, the German double-s character expands to "ss". 

In the system resource file for Great Britain, the localization routine 
in international resource 1 orders the pound currency sign between 
double quote and the pound weight sign (see Figure 1-8). For the 
United States., France, and Italy, the localization routine does 
nothing. 


$22 •'«»-« 

$A3 t 
$23 # 

Figure 1-8. Special Ordering for Great Britain 


Assembly-language note : The null localization routine consists 
of an RTS instruction. 
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*** Information on how to write your own localization routine is 
forthcoming. *** 


Using the International Utilities Package 

This section discusses how the routines in the International Utilities 
package fit into the general flow of an application program, and gives 
you an idea of which routines you'll need to use. The routines 
themselves are described in detail in the next section. 

The International Utilities Package is automatically read into memory 
from the system resource file when one of its routines is called. When 
a routine needs to access an international resource, it asks the 
Resource Manager to read the resource into memory. Together, the 
package and its resources occupy about 2K bytes. 

As described in the *** not yet existing *** Operating System Utilities 
manual, you can get the date and time as a long integer from the 
utility routine ReadDateTime. If you need a string corresponding to 
the date or time, you can pass this long integer to the IUDateStrlng or 
IUTimeString procedure in the International Utilities Package. These 
procedures determine the local format from the international resources 
read into memory by the Resource Manager (that is, resource type *INTL' 
and resource ID 0 or 1). In some situations, you may need the format 
information to come Instead from an international resource that you 
specify by its handle; if so, you can use IUDatePString or 
IUTimePString. This is useful, for example, if you want to use an 
international resource in a document's resource file after you've 
closed that file. 

Applications that use measurements, such as on a ruler for setting 
margins and tabs, can call IUMe trie to find out whether to use the 
metric system. This function simply returns the value of the 
corresponding field in international resource 0. To access any other 
fields in an international resource— say , the currency format in 
international resource 0— call IUGetlntl to get a handle to the 
resource. If you change any of the fields and want to write the 
changed resource to a resource file, the IUSetlntl procedure lets you 
do this. 

To sort strings, you can use IUCompString or, if you're not dealing 
with Pascal strings, the more general IUMagString. These routines 
compare two strings and give their exact relationship, whether equal, 
less than, or greater than. Subtleties like diacritical marks and case 
differences are taken into consideration, as described above under 
"International String Comparison". If you need to know only whether 
two strings are equal, and want to ignore the subtleties, use 
IUEqualString (or the more general IUMaglDString) instead. 

(note) 

The Operating System utility routine Equalstring also 
compares two Pascal strings for equality. It's less 
sophisticated than IUEqualString in that it follows ASCII 
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order more strictly; for details, see the Operating 
System Utilities manual *** eventually ***• 


International Utilities Package Routines 


As sembly-language note : The macros for calling the 
International Utilities Package routines push one of the 
following routine selectors onto the stack and then invoke 
Pack6 : 


Routine 

IUDatePString 

lUDateString 

IUGetlntl 

IUMaglDString 

IUMagString 

IUMetric 

IUTimePString 

IUTime String 

IUSetlntl 


Selector 

14 

0 

6 

12 

10 

4 

16 

2 

8 




PROCEDURE lUDateString (dateTime: Longlnt; form: DateForm; VAR result: 
Str255) ; 

Given a date and time as returned by the Operating System Utility 
routine ReadDateTlme , lUDateString returns in the result parameter a 
string that represents the corresponding date. The form parameter has 
the following data type: 

TYPE DateForm • (short Date, longDate, abbrevDate); 

ShortDate requests the short date format, longDate the long date, and 
abbrevDate the abbreviated long date. lUDateString determines the 
exact format from international resource 0 for the short date or 1 for 
the long date. See Figure 1-1 above for examples of the standard 
formats. Notice that the short date contains a space in place of a 
leading zero when the format specifies "no leading zero", so the length 
of the result is always the same for short dates. 

If the abbreviated long date is requested and the abbreviation length 
in international resource 1 is greater than the actual length of the 
name being abbreviated, lUDateString fills the 'abbreviation with NUL 
characters; the abbreviation length should not be greater than 15, the 
maximum name length. 
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PROCEDURE IUDatePStrlng (dateTime: Longlnt; form: DateForm; VAR result: 
Str2S5; IntlParam: Handle); 

IUDatePStrlng Is the same as IUDateString except that It determines the 
exact format of the date from the resource whose handle Is passed In 
IntlParam, overriding the resource that would otherwise be used* 


PROCEDURE IUTimeString (dateTime: Longlnt; wantSeconds: BOOLEAN; VAR 
result: Str255); 

Given a date and time as returned by the Operating System Utility 
routine ReadDateTime , IUTimeString returns in the result parameter a 
string that represents the corresponding time of day* If wantSeconds 
is TRUE, seconds are included in the time; otherwise, only the hour and 
minute are included. IUTimeString determines the time format from 
international resource 0. See Figure I - 1 above for examples of the 
standard formats* Notice that the time contains a space in place of a 
leading zero when the format specifies "no leading zero", so the length 
of the result is always the same* 


PROCEDURE IUTimePString (dateTime: Longlnt; wantSeconds: BOOLEAN; VAR 
result: Str255; IntlParam: Handle); 

IUTimePString is the same as IUTimeString except that it determines the 
time format from the resource whose handle is passed in IntlParam, 
overriding the resource that would otherwise be used. 


FUNCTION IUMetric : BOOLEAN; 

If international resource 0 specifies that the metric system is to be 
used, IUMetric returns TRUE; otherwise, it returns FALSE. 


FUNCTION IUGetlntl (thelD: INTEGER) : Handle; 

IUGetlntl returns a handle to the international resource numbered thelD 
(0 or 1). It calls the Resource Manager function 
GetResource( 'INTL' ,theID). For example, if you want to access 
individual fields of international resource 0, you can do the 
following: 

VAR myHndl: Handle; 
int0: Intl0Hndl; 

• • • 

myHndl :- IUGetIntl(0) ; 
int0 :- POINTER(ORD( myHndl)); 
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PROCEDURE IUSetlntl (refNums INTEGER; the ID: INTEGER; intlParam: 
Handle); 

In the resource file having the reference number refNum, IUSetlntl sets 
the international resource numbered thelD (0 or 1) to the data pointed 
to by intlParam* The data may be either an existing resource or data 
that hasn't yet been written to a resource file* IUSetlntl adds the 
resource to the specified file or replaces the resource if it's already 
there* 


FUNCTION IUCompString (aStr.bStr: Str255) : INTEGER; [Pascal only] 

IUCompStrlng compares aStr and bStr as described above under 
"International String Comparison" , taking both primary and secondary 
ordering into consideration* It returns one of the values listed 
below* 


Result 

Meaning 

Example 


aStr 

bStr 

-I 

aStr is less than bStr 

•Ab' 

•ab' 

0 

aStr equals bStr 

' Ab ' 

'Ab' 

1 

aStr is greater than bStr 

'Ac' 

'ab' 


Assembly-language note : IUCompString was created for the 
convenience of Pascal programmers; there's no trap for it* It 
eventually calls IUMagString ( which is what you should use from 
assembly language. 


FUNCTION IUMagString (aPtr.bPtr: Ptr; aLen.bLen: INTEGER) : INTEGER; 

lUMagString is the same as IUCompString (above) except that instead of 
comparing two Pascal strings, it compares the string defined by aPtr 
and aLen to the string defined by bPtr and bLen* The pointer points to 
the first character of the string (any byte in memory, not necessarily 
word— aligned ) , and the length specifies the number of characters in the 
string. 


FUNCTION IUEqualString (aStr,bStr: Str255) : INTEGER; [Pascal only] 

IUEqualStrlng compares aStr and bStr for equality without regard for 
secondary ordering, as described above under "International String 
Comparison". If the strings are equal, it returns 0; otherwise, it 
returns 1. For example, if the strings are 'Rose' and 'rose', 
IUEqualString considers them equal and returns 0. 
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(note) 

See also Equalstring In the Operating System Utilities 
manual *** doesn’t yet exist ***. 


Assembly-language note : IUEqualStrlng was created for the 
convenience of Pascal programmers; there's no trap for it. It 
eventually calls IUMaglDString, which is what you should use 
from assembly language. 


FUNCTION IUMaglDString (aPtr.bPtr: Ptr; aLen,bLen: INTEGER) : INTEGER; 

IUMaglDString is the same as IUEqualString (above) except that instead 
of comparing two Pascal strings, it compares the string defined by aPtr 
and aLen to the string defined by bPtr and bLen. The pointer points to 
the first character of the string (any byte in memory, not necessarily 
word -aligned ) , and the length specifies the number of characters in the 
string. 
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THE BINARY-DECIMAL CONVERSION PACKAGE 


The Binary-Decimal Conversion Package contains only two routines: one 
converts an integer from its internal (binary) form to a string that 
represents its decimal (base 10) value; the other converts a decimal 
string to the corresponding integer* 

*** In the Inside Macintosh manual , the documentation of this package 
will be at the end of the volume that describes the User Interface 
Toolbox. *** 

You should already be familiar with the Package Manager, and packages 
in general. 

The Binary-Decimal Conversion Package is automatically read into memory 
when one of its routines is called; it occupies a total of about 200 
bytes. The routines are described below. They're register-based, so 
the Pascal form of each is followed by a box containing information 
needed to use the routine from assembly language. (For general 
information on using assembly language , see Programming Macintosh 
Applications in Assembly Language . ) 


Assembly-language note : The macros for calling the 
Binary-Decimal Conversion Package routines push one of the 
following routine selectors onto the stack and then invoke 
_Pack7: 

Routine Selector 

NumToString 0 

StringToNum 1 


PROCEDURE NumToString (theNum: Longlnt; VAR theString: Str255); 


Trap macro 

_NumToString 

On entry 

A0: 

pointer to theString (length byte followed 
by characters) 


D0 : 

theNum (long integer) 

On exit 

A0 : 

pointer to theString 


NumToString converts theNum to a string that represents its decimal 
value, and returns the result in theString. If the value is negative, 
the string begins with a minus sign; otherwise, the sign is omitted. 
Leading zeroes are suppressed, except that the value 0 produces '0'. 
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For example: 

theNum 

12 

-23 

0 


theStrlng 

' 12 ' 

• -23* 
’ 0 * 


PROCEDURE StringToNum (theStrlng: Str255; VAR theNum: Longlnt); 


Trap macro 

_StringToNum 

On entry 

A0: 

pointer to theStrlng (length byte followed 
by characters) 

On exit 

D0: 

theNum (long Integer) 


Given a string representing a decimal integer, StringToNum converts it 
to the corresponding integer and returns the result in theNum. The 
string may begin with a plus or minus sign. For example: 

theStrl ng theNum 

' 12 ' 12 

'-23' -23 

'- 0 ' 0 

'055' 55 

The magnitude of the integer is converted modulo 2*32, and the 32-bit 
result is negated if the string begins with a minus sign; integer 
overflow occurs if the magnitude is greater than 2*31-1. (Negation is 
done by taking the two's complement — reversing the state of each bit 
and then adding 1.) For example: 

theStrlng 

'2147483648' (magnitude is 2*31) 

'-2147483648' 

'4294967295' (magnitude is 2*32-1) 

'-4294967295' 

StringToNum doesn't actually check whether the characters in the string 
are between '0' and '9'; instead, since the ASCII codes for '0' through 
'9' are $30 through $39, it just masks off the last four bits and uses 
them as a digit. For example, '2:' is converted to the number 30 
because the ASCII code for ':' is $3A. Leading spaces before the first 
digit are treated as zeroes, since the ASCII code for a space is $20. 
Given that the ASCII codes for 'C', 'A', and 'T' are $43, $41, and $54, 
respectively, consider the following examples: 


theNum 

-2147483648 

-2147483648 

-l 

1 
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theString theNum 


•CAT' 

314 

+CAT’ 

314 

-GAT’ 

-314 
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THE STANDARD FILE PACKAGE 


The Standard File Package provides the standard user interface for 
specifying a file to be saved or opened* It allows the file to be on a 
disk in any drive connected to the Macintosh, and lets a currently 
Inserted disk be ejected so that another one can be inserted* 

*** In the Inside Macintosh manual, the documentation of this package 
will be at the end of the volume that describes the Toolbox* *** 

You should already be familiar with the following: 

“ the basic concepts and structures behind QuickDraw, particularly 
points and rectangles 

- the Toolbox Event Manager 

- the Dialog Manager, especially the ModalDialog procedure 
~ the Package Manager and packages in general 


About the Standard File Package 

Standard Macintosh applications should have a File menu from which the 
user can save and open documents, via the Save, Save As, and Open 
commands* In response to these commands, the application can call the 
Standard File Package to find out the document name and let the user 
switch disks if desired* As described below, a dialog box is presented 
for this purpose* (More details and illustrations are given later in 
the descriptions of the individual routines.) 

When the user chooses Save As, or Save when the document is untitled, 
the application needs a name for the document* The corresponding 
dialog box lets the user enter the document name and click a button 
labeled "Save" (or just click "Cancel" to abort the command)* By 
convention, the dialog box comes up displaying the current document 
name, if any, so the user can edit it. 

In response to an Open command, the application needs to know which 
document to open* The corresponding dialog box displays the names of 
all documents that might be opened, and the user chooses one by 
clicking it and then clicking a button labeled "Open". A vertical 
scroll bar allows scrolling through the names if there are more than 
can be shown at once. 

Both of these dialog boxes let the user: 

- insert a disk in an external drive connected to the Macintosh 
“ eject a disk from either drive and insert another 
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- initialize and name an Inserted disk that's uninitialized 

- switch from one drive to another 

On the right in the dialog box, separated from the rest of the box by a 
gray line, there's a disk name with one or two buttons below it; Figure 
S-l shows what this looks like when an external drive is connected to 
the Macintosh but currently has no disk in it. Notice that the Drive 
button is inactive (dimed). After the user inserts a disk in the 
external drive (and, if necessary, initializes and names it), the Drive 
button becomes active. If there's no external drive, the Drive button 
isn't displayed at all. 



The disk name displayed in the dialog box is the name of the current 
disk, initially the disk you used to start up the Macintosh, The user 

can click Eject to eject the current disk and insert another, which 

then becomes the current disk. If there's an external drive, clicking 

the Drive button changes the current disk from the one in the external 

drive to the one in the internal drive or vice versa. The Drive button 
is inactive whenever there's only one disk inserted. 

If an uninitialized or otherwise unreadable disk is inserted, the 
Standard File Package calls the Disk Initialization Package to provide 
the standard user interface for initializing and naming a disk. 


Using the Standard File Package 

This section discusses how the routines in the Standard File Package 
fit into the general flow of an application program, and gives you an 
idea of which routines you'll need to use. The routines themselves are 
described in detail in the next section. 

The Standard File Package and the resources it uses are automatically 
read into memory when one of its routines is called. It in turn reads 
the Disk Initialization Package into memory if a disk is ejected; 
together they occupy about 6«5K bytes. 

Call SFPutFile when your application is to save to a file and needs to 
get the name of the file from the user. Standard applications should 
do this when the user chooses Save As from the File menu, or Save when 
the document is untitled, SFPutFile displays a dialog box allowing the 
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user Co enter a file name* 


Similarly, SFGetFile is useful whenever your application is to open a 
file and needs to know which one, such as when the user chooses the 
Open command from a standard application's File menu* SFGetFile 
displays a dialog box with a list of file names to choose from* 


You pass these routines a reply record, as shown below, and they fill 
it with information about the user's reply* 


TYPE SFReply - RECORD 

good: BOOLEAN; 

copy: BOOLEAN; 

f Type : OSType ; 

vRefNum: INTEGER; 
version: INTEGER; 
fName: STRING [63] 

END; 


(FALSE if Ignore command} 
(not used} 

(file type or not used} 
(volume reference number} 
(file's version number} 
(file name} 


The first field of this record determines whether the file operation 
should take place or the command should be ignored (because the user 
clicked the Cancel button in the dialog box)* The fType field is used 
by SFGetFile to store the file's type. The vRefNum, version, and fName 
fields identify the file chosen by the user; the application passes 
their values on to the File Manager routine that does the actual file 
operation. VRefNum contains the volume reference number of the volume 
containing the file. Currently the version field always contains 0; 
the use of nonzero version numbers is not supported by this package* 

For more information on files, volumes, and file operations, see the 
File Manager manual *** doesn't yet exist ***. 

Both SFPutFile and SFGetFile allow you to use a nonstandard dialog box; 
two additional routines, SFPPutFile and SFPGetFile, provide an even 
more convenient and powerful way of doing this. 


Standard File Package Routines 


Assembly-language note : The macros for calling the Standard 
File Package routines push one of the following routine 
selectors onto the stack and then invoke Pack3: 


Routine 

SFGetFile 

SFPGetFile 

SFPPutFile 

SFPutFile 


Selector 

2 

4 

3 

1 
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PROCEDURE SFPutFile (where: Point; prompt: Str255; oirigName: Str255; 
dlgHook: ProcPtr; VAR reply: SFReply); 

SFPutFile displays a dialog box allowing the user to specify a file to 
which data will be written (as during a Save or Save A a command)* It 
then repeatedly gets and handles events until the user either confirms 
the command after entering an appropriate file name or aborts the 
command by clicking Cancel in the dialog* It reports the user 8 reply 
by filling the fields of the reply record specified by the reply 
parameter , as described above; the fType field of this record isn t 
used « 

The general appearance of the standard SFPutFile dialog box is shown in 
Figure S-2. The where parameter specifies the location of the top left 
corner of the dialog box in global coordinates. The prompt parameter 
is a line of text to be displayed as a s Cat Text item in the dialog box, 
where shown in Figure S-2. The origName parameter contains text that 
appears as an enabled, selected editText item; for the standard 
document— saving commands, it should be the current name of the 
document, or the empty string (to display an insertion point) if the 
document hasn't been named yet* 


prompt 
oripName 


-» Save current document os: 


file name 


[ Saue j [ Cancel ] 


>2 

n 

disk name 

!i 

[ Eject J 



) 

f Drive J 


Figure S-2. Standard SFPutFile Dialog 




If you want to use the standard SFPutFile dialog box, pass NIL for 
dlgHook; otherwise, see the information for advanced programmers below. 

SFPutFile repeatedly calls the Dialog Manager procedure ModalDialog. 
When an event involving an enabled dialog item occurs , ModalDialog 
handles the event and returns the item number, and SFPutFile responds 
as follows: 

- If the Eject or Drive button is clicked, or a disk is inserted, 
SFPutFile responds as described above under "About the Standard 
File Package". 

- Text entered into the editText item is stored in the fName field 
of the reply record. (SFPutFile keeps track of whether there s 
currently any text in the item, and makes the Save button inactive 
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- if the Save button is clicked, SFPutFile determines whether the 
file name in the fName field of the reply record is appropriate. 
If so, it returns control to the application with the first field 
of the reply record set to TRUE; otherwise, it responds 
accordingly, as described below. 

- if the Cancel button in the dialog is clicked, SFPutFile returns 
control to the application with the first field of the reply 
record set to FALSE. 

(note) 

Notice that disk insertion is one of the user actions 
listed above, even though ModalDialog normally ignores 
disk-inserted events. The reason this works is that 
SFPutFile calls ModalDialog with a fllterProc function 
that checks for a disk-inserted event and returns a 
"fake", very large item number if one occurs; SFPutFile 
recognizes this item number as an indication that a disk 
was inserted. 

The situations that may cause an entered name to be inappropriate, and 

SFPutFile 's response to each, are as follows: 

- If a file with the specified name already exists on the disk and 
is different from what was passed in the origName parameter, the 
alert in Figure S-3 is displayed. If the user clicks Yes, the 
file name is appropriate. 


Replace existing 
'file name” ? 

L ] | No | 


Figure S-3. Alert for Existing File 


- If the disk to which the file should be written is locked, the 
alert in Figure S-4 is displayed. If a system error occurs, a 
similar alert is displayed, with a corresponding message 
explaining the problem. 
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Figure S-4. Alert for Locked Disk 


(note) 

The user may specify a disk name (preceding the file name 

and separated from it by a colon). If the disk isn't ^ 

currently in a drive, an alert similar to the one in 

Figure S-4 is displayed. The ability to specify a disk 

name is supported for historical reasons only; users 

should not be encouraged to do it. 

After the user clicks No or Cancel in response to one of these alerts, 
SFPutFlle dismisses the alert box and continues handling events (so a 
different name may be entered). 

Advanced programmers : You can create your own dialog box rather than 
use the standard SFPutFile dialog. To do this, you must provide your 
own dialog template and store it in your application's resource file 
with the same resource ID that the standard template has in the system 
resource file: 

CONST putDIgID - -3999; {SFPutFile dialog template ID} 

(note) 

The SFPPutFile procedure, described below, lets you use 
any resource ID for your nonstandard dialog box. 

Your dialog template must specify that the dialog window be invisible, 
and your dialog must contain all the standard items, as listed below. 

The appearance and location of these items in your dialog may be 
different. You can make an item "invisible" by giving it a display 
rectangle that's off the screen. The display rectangle for each item 
in the standard dialog box is given below. The rectangle for the 
standard dialog box itself is (0, 0, 304, 104). 
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Item number 
1 
2 

3 

4 

5 

6 

7 

8 


Item 

Save button 

Cancel button 

Prompt string (statText) 

Userltem for disk name 

Eject button 

Drive button 

EditText item for file name 
Userltem for gray line 


Standard display rectangle 
(12, 74, 82, 92) 

(114, 74, 184, 92) 

(12, 12, 184, 28) 

(209, 16, 295, 34) 

(217, 43, 287, 61) 

(217, 74, 287, 92) 

(14, 34, 182, 50) 

(200, 16, 201, 88) 


(note) 

Remember that the display rectangle for any "invisible” 
item must be at least about 20 pixels wide. *** This 
will be discussed in a future draft of the Dialog Manager 
manual . *** 


If your dialog has additional items beyond the the standard ones, or if 
you want to handle any of the standard items in a nonstandard manner, 
you must write your own dlgHook function and point to it with dlgHook. 
Your dlgHook function should have two parameters and return an integer 
value. For example, this is how it would be declared if it were named 
My Dig : 


FUNCTION My Dig (item: INTEGER; theDialog: DialogPtr) : INTEGER; 


Immediately after calling ModalDialog, SFPutFile calls your dlgHook 
function, passing it the item number returned by ModalDialog and a 
pointer to the dialog record describing your dialog box. Using these 
two parameters , your dlgHook function should determine how to handle 
the event. There are o rede fined constants for the Item niimhers of 


standard enabled items, as 

follows : 

CONST put Save ■ 1; 

{Save button} 

putCancel * 2; 

{Cancel button} 

putEject ■ 5; 

{Eject button} 

putDrive = 6; 

{Drive button} 

put Name * 7 ; 

{editText item for file name} 


ModalDialog also returns the "fake" item number 100 when a disk' 
inserted event occurs, as detected by its filterProc function. 


After handling the event (or, perhaps, after ignoring it) the dlgHook 
function must return an item number to SFPutFile. If the item number 
is one of those listed above, SFPutFile responds in the standard way; 
otherwise, it does nothing. 

(note) 

For advanced programmers who want to change the 
appearance of the alerts displayed when an inappropriate 
file name is entered, the resource IDs of those alerts in 
the system resource file are listed below. 
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Alert 

Existing file 
Locked disk 
System error 
Disk not found 


Resource ID 
-3996 
-3997 
-3995 
-3994 


PROCEDURE SFPPutFile (where: Point; prompt: Str255; origName: Str255; 

dlgHook: ProcPtr; VAR reply: SFReply; dlglD: .INTEGER; 
filterProc: ProcPtr); 

SFPPutFile is an alternative to SFPutFile for advanced prograimners who 
want to use a nonstandard dialog box* It's the same as SFPutFile 
except for the two additional parameters dlglD and filterProc* 

DlglD is the resource ID of the dialog template to be used instead of 
the standard one (so you can use whatever ID you wish rather than the 
same one as the standard)* 

The filterProc parameter determines how ModalDialog will filter events 
when called by SFPPutFile. If filterProc is NIL, ModalDialog does the 
standard filtering that it does when called by SFPutFile; otherwise, 
filterProc should point to a function for ModalDialog to execute after 
doing the standard filtering* The function must be the same as one 
you'd pass directly to ModalDialog in its filterProc parameter. (See 
the Dialog Manager manual for more information*) 


PROCEDURE SFGetFile (where: Point; prompt: Str255; fileFilter: ProcPtr; 

numTypes : INTEGER; typeList: SFTypeList; dlgHook: ProcPtr; 
VAR reply: SFReply); 

SFGetFile displays a dialog box listing the names of a specific group 
of files from which the user can select one to be opened (as during an 
Open command). It then repeatedly gets and handles events until the 
user either confirms the command after choosing a file name or aborts 
the command by clicking Cancel in the dialog. It reports the user's 
reply by filling the fields of the reply record specified by the reply 
parameter, as described above under "Using the Standard File Package". 

The general appearance of the standard SFGetFile dialog box is shown in 
Figure S-5* File names are sorted in order of the ASCII codes of their 
characters, ignoring diacritical marks and mapping lowercase characters 
to their uppercase equivalents. If there are more file names than can 
be displayed at one time, the scroll bar is active; otherwise, the 
scroll bar is inactive. 
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file 1 name 
file2nome 
file3name 

5 


disk name 

r 

[ Open ] 





l IJeet J 

file5 name 
file6name 
file 7 name 

|i;: 

&& 


[ Cancel ] 

[ Driue ) 

2 




Figure S-5. Standard SFGetFile Dialog 

The where parameter specifies the location of the top left corner of 
the dialog box in global coordinates. The prompt parameter is ignored; 
it's there for historical purposes only. 

The flleFilter, numTypes , and typeList parameters determine which files 
appear in the dialog box. SFGetFile first looks at numTypes and 
typeList to determine what types of files to display, then it executes 
the function pointed to by flleFilter (if any) to do additional 
filtering on which files to display. File types are discussed in the 
manual The Structure of a_ Macintosh Application . For example , if the 
application is concerned only with pictures, you won't want to display 
the names of any text files. 

Pass -1 for numTypes to display all types of files; otherwise, pass the 
number of file types you want to display, and pass the types themselves 
in typeList. The SFTypeList data type is defined as follows: 

TYPE SFTypeList - ARRAY 10..3] OF OSType; 


(note) 

This array is declared for a reasonable maximum number of 
types (four). If you need to specify more than four 
types, declare your own array type with the desired 
number of entries (and use the @ operator to pass a 
pointer to it). 

If flleFilter isn't NIL, SFGetFile executes the function it points to 
for each file, to determine whether the file should be displayed. The 
flleFilter function has one parameter and returns a Boolean value. For 
example : 

FUNCTION MyFileFilter (paramBlock: ParmBlkPtr) : BOOLEAN; 

SFGetFile passes this function the file information it gets by calling 
the File Manager procedure PBGetFInfo (see the *** forthcoming *** File 
Manager manual for details). The function selects which files should 
appear in the dialog by returning FALSE for every file that should be 
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shown and TRUE for every file that shouldn't be shown. 

(note) 

As described in the File Manager manual, a flag can be 
set that tells the Finder not to display a particular 
file's icon on the desktop; this has no effect on whether 
SFGetFile will list the file name* 

If you want to use the standard SFGetFile dialog box, pass NIL for 
dlgHook; otherwise, see the information for advanced programmers below. 

Like SFPutFile , SFGetFile repeatedly calls the Dialog Manager procedure 
ModalDlalog. When an event involving an enabled dialog item occurs, 
ModalDialog handles the event and returns the item number, and 
SFGetFile responds as follows: 

- if the Eject or Drive button is clicked, or a disk is inserted, 
SFGetFile responds as described above under "About the Standard 
File Package". 

- If clicking or dragging occurs in the scroll bar , the contents of 
the dialog box are redrawn accordingly. 

- If a file name is clicked, it's selected and stored in the fName 
field of the reply record. (SFGetFile keeps track of whether a 
file name is currently selected, and makes the Open button 
Inactive if not.) 

- If the Open button is clicked, SFGetFile returns control to the 
application with the first field of the reply record set to TRUE. 

- If a file name is double-clicked, SFGetFile responds as if the 
user clicked the file name and then the Open button. 

- If the Cancel button in the dialog is clicked, SFGetFile returns 
control to the application with the first field of the reply 
record set to FALSE. 

If a key (other than a modifier key) is pressed, SFGetFile selects the 
first file name starting with the character typed. If no file name 
starts with that character, it selects the first file name starting 
with a character whose ASCII code is greater than the character typed. 

Advanced programmers: You can create your own dialog box rather than 
use the standard SFGetFile dialog. To do this, you must provide your 
own dialog template and store it in your application's resource file 
with the same resource ID that the standard template has in the system 
resource file: 

CONST getDIgID » -4000; {SFGetFile dialog template ID} 


(note) 

The SFPGetFile procedure, described below, lets you use 
any resource ID for your nonstandard dialog box. 
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Your dialog template must specify that the dialog window be invisible, 
and your dialog must contain all the standard items, as listed below* 
The appearance and location of these items in your dialog may be 
different* You can make an item "invisible" by giving it a display 
rectangle that's off the screen* The display rectangle for each in the 


standard dialog box is given below. The rectangle for the standard 
dialog box Itself is (0, 0, 348, 136). 

Item number 

Item 

Standard display rectangle 

1 

Open button 

(152, 28, 232, 46) 

2 

Invisible button 

(1152, 59, 1232, 77) 

3 

Cancel button 

(152, 90, 232, 108) 

4 

Userltem for disk name 

(248, 28, 344, 46) 

5 

Eject button 

(256, 59, 336, 77) 

6 

Drive button 

(256, 90, 336, 108) 

7 

Userltem for file name list 

(12, 11, 125, 125) 

8 

Userltem for scroll bar 

(124, 11, 140, 125) 

9 

Userltem for gray line 

(244, 20, 245, 116) 

10 

Invisible text (statText) 

(1044, 20, 1145, 116) 


If your dialog has additional items beyond the the standard ones, or if 
you want to handle any of the standard items in a nonstandard manner, 
you must write your own dlgHook function and point to it with dlgHook* 
Your dlgHook function should have two parameters and return an Integer 
value* For example, this is how it would be declared if it were named 
My Dig: 


FUNCTION My Dig (item: INTEGER; theDialog: DialogPtr) : INTEGER; 

Immediately after calling ModalDialog, SFGetFile calls your dlgHook 
function, passing it the item number returned by ModalDialog and a 
pointer :o the dialog record describing your dialog box* Using these 
two parameters, your dlgHook function should determine how to handle 
the event. There are predefined constants for the item numbers of 
standard enabled items, as follows: 


CONST getOpen - 1 
getCancel “ 3 
getEject ” 5 
get Drive ■ 6 
getNmList * 7 
getScroll ■ 8 


(Open button} 

(Cancel button} 

(Eject button} 

(Drive button} 

(userltem for file name list} 
(userltem for scroll bar} 


ModalDialog also returns "fake" item numbers in the following 
situations, which are detected by its filterProc function: 


- When a disk-inserted event occurs, it returns 100. 


When a key-down event occurs, it returns 1000 plus the ASCII code 
of the character. 


After handling the event (or, perhaps, after ignoring it) your dlgHook 
function must return an item number to SFGetFile* If the item number 
is one of those listed above, SFGetFile responds in the standard way; 
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otherwise t it does nothing. 


PROCEDURE SFPGetFile (where: Point; prompt: Str255; fileFllter: 

ProcPtr; numTypes: INTEGER; typeList: SFTypeList; dlgHook: 
ProcPtr; VAR reply: SFReply; dig ID: INTEGER; filterProc: 
ProcPtr); 

SFPGetFile is an alternative to SFGetFile for advanced programmers who 
want to use a nonstandard dialog box. It's the same as SFGetFile 
except for the two additional parameters dlglD and filterProc. 

DlglD is the resource ID of the dialog template to be used instead of 
the standard one (so you can use whatever ID you wish rather than the 
same one as the standard). 

The filterProc parameter determines how ModalDialog will filter events 
when called by SFPGetFile. If filterProc is NIL, ModalDialog does the 
standard filtering that it does when called by SFGetFile; otherwise, 
filterProc should point to a function for ModalDialog to execute after 
doing the standard filtering. Note, however, that the standard 
filtering will detect key-down events only if the dialog template ID is 
the standard one. 
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THE DISK INITIALIZATION PACKAGE 


The Disk Initialization Package provides routines for initializing 
disks to be accessed with the Macintosh Operating System's File Manager 
and Disk Driver. A single routine lets you easily present the standard 
user interface for initializing and naming a disk; the Standard File 
Package calls this routine when the user inserts an uninitialized disk. 
You can also use the Disk Initialization Package to perform each' of the 
three steps of initializing a disk separately if desired. 

*** In the Inside Macintosh manual , the documentation of this package 
will be at the end of the volume that describes the Operating System. 
*** 

You should already be familiar with the following: 

- the basic concepts and structures behind QuickDraw, particularly 
points 

- the Toolbox Event Manager 

- the File Manager *** the File Manager manual doesn't yet exist *** 

- the Package Manager and packages in general 


Using the Disk Initialization Package 

This section discusses how the routines in the Disk Initialization 
package fit into the general flow of an application program, and gives 
you an idea of which routines you'll need to use. The routines 
themselves are described in detail in the next section. 

The Disk Initialization Package and the resources it uses are 
automatically read into memory from the system resource file when one 
of the routines in the package is called. Together, the package and 
its resources occupy about 2.5K bytes. If the disk containing the 
system resource file isn't currently in a Macintosh disk drive, the 
user will be asked to switch disks and so may have to remove the one to 
be initialized. To avoid this, you can use the DILoad procedure, which 
explicitly reads the necessary resources into memory and makes them 
unpurgeable. You would need to call DILoad before explicitly ejecting 
the system disk or before any situations where it may be switched with 
another disk (except for situations handled by the Standard File 
Package, which calls DILoad itself). 

(note) 

The resources used by the Disk Initialization Package 
consist of a single dialog and its associated items, even 
■ though the package may present what seem to be a number 
of different dialogs. A special technique was used to 
allow the single dialog to contain all possible dialog 
items with only some of them visible at one time. *** 
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This technique will be documented in the next draft of 
the Dialog Manager manual* *** 

When you no longer need to have the Disk Initialization Package in 
memory, call DIUnload. The Standard File Package calls DIUnload before 
returning* 

When a disk-inserted event occurs, the system attempts to mount the 
volume (by calling the File Manager function PBMountVol) and returns 
PBMountVol's result code in the high-order word of the event message. 

In response to such an event, your application can examine the result 
code in the event message and call DIBadMount if an error occurred 
(that is, if the volume could not be mounted)* If the error is one 
that can be corrected by initializing the disk, DIBadMount presents the 
standard user interface for initializing and naming the disk, and then 
mount s the volume itself* For other errors, it justs ejects the disk, 
these errors are rare, and may reflect a problem in your program* 

(note) 

Disk-inserted events during standard file saving and 
opening are handled by the Standard File Package* You'll 
call DIBadMount only in other, less common situations 
(for example, if your program explicitly ejects disks, or 
if you want to respond to the user's inserting an 
uninitialized disk when not expected). 

Disk initialization consists of three steps, each of which can be 
performed separately by the functions DIFormat, DIVerify, and DIZero. 
Normally you won't call these in a standard application, but they may 
be useful in special utility programs that have a nonstandard 
interface. 


Disk Initialization Package Routines 




Assembly— language note : The macros for calling the Disk 
Initialization Package routines push one of the following 
routine selectors onto the stack and then invoke _Pack2i 


Routine 

DIBadMount 

DIFormat 

DILoad 

DIUnload 

DIVerify 

DIZero 


Selector 

0 

6 

2 

4 

8 

10 
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PROCEDURE DILoad; 

DILoad reads Che Disk Inlciallzaclon Package, and Its associated dialog 
and dialog items, from the system resource file into memory and makes 
them unpurgeable. 

(note) 

DIFormat, DIVerify, and DIZero don't need the dialog, so 
if you use only these routines you can call the Resource 
Manager function GetResource to read just the package 
resource into memory (and the Memory Manager procedure 
HNo Purge to make it unpurgeable)* 


PROCEDURE DIUnload ; 

DIUnload makes the Disk Initialization Package (and its associated 
dialog and dialog items) purgeable* 


FUNCTION DIBadMount (where: Point; evtMessage: Longlnt) : INTEGER; 

Call DIBadMount when a disk-inserted event occurs if the result code in 
the high-order word of the associated event message indicates an error 
(that is, the result code is other than noErr)* Given the event 
message in evtMessage, DIBadMount evaluates the result code and either 
ejects the disk or lets the user initialize and name it* The low-order 
word of the event message contains the drive number* The where 
parameter specifies the location (in global coordinates) of the top 
left corner of the dialog box displayed by DIBadMount* 

If the result code passed is extFSErr, mFulErr, nsDrvErr, paramErr, or 
volOnLinErr, DIBadMount simply ejects the disk from the drive and 
returns the result code. If the result code loErr, badMDBErr, or 
noMacDskErr is passed, the error can be corrected by initializing the 
disk; DIBadMount displays a dialog box that describes the problem and 
asks whether the user wants to initialize the disk* For the result 
code loErr, the dialog box shown in Figure D—l is displayed* (This 
happens if the disk is brand new.) For badMDBErr and noMacDskErr, 
DIBadMount displays a similar dialog box in which the description of 
the problem is "This disk is damaged" and "This is not a Macintosh 
disk", respectively. 



This disk Is unreadable: 

Do you want to initialize it? 


I Eject 1 [ Initialize! 


Figure I>-1. Disk Initialization Dialog for IOErr 
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(note) 

Before presenting the disk initialization dialog t 
DIBadMount checks whether the drive contains an already 
mounted volume; if so, it ejects the disk and returns 2 
as its result* This will happen rarely and may reflect 
an error in your program (for example, you forgot to call 
DILoad and the user had to switch to the disk containing 
the system resource file)* 

If the user responds to the disk initialization dialog by clicking the 
Eject button, DIBadMount ejects the disk and returns 1 as its result* 

If the Initialize button is clicked, a box displaying the message 
"Initializing disk***" appears, and DIBadMount attempts to initialize 
the disk. If initialization falls, the disk is ejected and the user is 
informed as shown in Figure D-2; after the user clicks OK, DIBadMount 
returns a negative result code ranging from firstDskEtr to lastDskErr, 
indicating that a low-level disk error occurred* 



Initialization foiled! 

H 

( OK - ) 


Figure D-2. Initialization Failure Dialog 


If the disk is successfully initialized, the dialog box in Figure D-3 
appears* After the user names the disk and clicks OK, DIBadMount 
mounts the volume by calling the File Manager function PBMountVol and 
returns PBMountVol 's result code (noErr if no error occurs)* 


T2T 

Please name this disk: 

LJ 


tun titled ' r ' T II 

1 

1 OK 1 


Figure D-3. Dialog for Naming a Disk 
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Result codes 


Other results 


noErr 

extFSErr 

mFulErr 

nsDrvErr 

paramErr 

volOnLinErr 

firstDskErr 

through lastDskErr 


No error 

External file system 
Memory full 
No such drive 
Bad drive number 
Volume already on-line 
Low-level disk error 


1 User clicked Eject 

2 Mounted volume in drive 


FUNCTION DIFormat (drvNum: INTEGER) : OSErr; 

DIFormat formats the disk in the drive specified by the given drive 
number and returns a result code indicating whether the formatting was 
completed successfully or failed* Formatting a disk consists of 
writing special information onto it so that the Disk Driver can read 
from and write to the disk* 

Result codes noErr No error 

firstDskErr Low-level disk error 

through lastDskErr 


FUNCTION DIVerify (drvNum: INTEGER) : OSErr; 

DIVerify verifies the format of the disk in the drive specified by the 
given drive number; it reads each bit from the disk and returns a 
result code indicating whether all bits were read successfully or not. 

Result codes noErr No error 

firstDskErr Low-level disk error 

through lastDskErr 


FUNCTION DIZero (drvNum: INTEGER; volName: Str255) : OSErr; 

On the unmounted volume in the drive specified by the given drive 
number, DIZero writes the volume information, a block map, and a file 
directory as for a volume with no files; the volName parameter 
specifies the volume name to be included in the volume information* 

This is the last step in initialization (after formatting and 
verifying) and makes any files that are already on the volume 
permanently inaccessible* If the operation fails, DIZero returns a 
result code indicating that a low-level disk error occurred; otherwise, 
it mount 8 the volume by calling the File Manager function PBMountVol 
and returns PBMountVol' s result code (noErr if no error occurs). 
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Result codes 


noErr 

badMDBErr 

extFSErr 

ioErr 

mFulErr 

noMacDskErr 

nsDrvErr 

paramErr 

volOnLinErr 

firstDskErr 

through lastDskErr 


No error 

Bad master directory block 

External file system 

Disk I/O error 

Memory full 

Not a Macintosh volume 

No such drive 

Bad drive number 

Volume already on-line 

Low-level disk error 
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SUMMARY OF THE PACKAGE MANAGER 


Constants 


CONST { Resource IDs for packages } 


dsklnit * 2; 
stdFile - 3; 
flPoint - 4; 
trFunc ■ 5; 
intUtil - 6; 
bdConv - 7 ; 


{Disk Initialization} 
{Standard File} 
{Floating-Point Arithmetic} 
{Transcendental Functions} 
{International Utilities} 
{Binary-Decimal Conversion} 


Routines 


PROCEDURE InitPack (packID: INTEGER); 
PROCEDURE InitAllPacks; 


Assembly-Language Information 


Constants 


Resource IDs for packages 


dsklnit 

.EQU 

2 

stdFile 

.EQU 

3 

flPoint 

.EQU 

4 

trFunc 

.EQU 

5 

intUtil 

.EQU 

6 

bdConv 

.EQU 

7 


Disk Initialization 
Standard File 
Floating-Point Arithmetic 
Transcendental Functions 
International Utilities 
Binary-Decimal Conversion 
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SUMMARY OF THE INTERNATIONAL UTILITIES PACKAGE 


Constants 


CONST { Masks for currency format } 

currSymLead “ 16; {set if currency symbol leads} 

currNegSym ■ 32; {set if minus sign for negative) 

currTrailingZ ■ 64; {set if trailing decimal zeroes} 

currLeadingZ * 128; {set if leading integer zero} 

{ Order of short date elements } 

mdy * 0; {month day year} 
dmy * 1; {day month year} 
ymd ■ 2; {year month day} 

{ Masks for short date format } 

dayLeadingZ • 32; {set if leading zero for day} 

mntLeadingZ ■ 64; {set if leading zero for month} 

century ■ 128; {set if century included} 

{ Masks for time format } 

secLeadingZ *32; {set if leading zero for seconds} 
minLeadingZ * 64; {set if leading zero for minutes} 

hrLeadingZ * 128; {set if leading zero for hours} 

{ High-order byte of version information } 

verUS ■ 0; 

verFrance ■ 1 ; 
verBritain - 2; 
verGermany ■ 3; 
verltaly ■ 4; 






Data Types 

TYPE Intl0Hndl - ~Intl0Ptr; 
Intl0Ptr * ~Intl0Rec; 
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Intl0Rec 


IntllHndl 

IntllPtr 

IntllRec 


DateForm * 
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- PACKED RECORD 
decimalPt: 
thousSep: 
listSep: 
currSyml : 
currSym2 : 
currSym3 : 
currFmt : 
dateOrder: 
shortDateFmt: 
dateSep: 
timeCycle : 
clmeFmt: 
raornStr : 

eveStr: 

time Sep: 
timelSuff : 
time2Suf f : 
time3Suf £ : 
time4Suf f : 
time5Suff : 
cime6Suf £ : 
time7 Suf f : 
time8Suff : 
metrlcSys : 
intl0Vers : 

END; 


CHAR 

CH&R 

CHAR 

CHAR 

CHAR 

CHAR 


{decimal point character} 
{thousands separator} 
{list separator} 

{currency symbol} 


Byte 

Byte 

Byte 

CHAR 

Byte 

Byte 


{currency format} 

{order of short date elements} 

{short date format} 

{date separator} 

{0 if 24-hour cycle, 255 if 12-hour} 
{time format} 


PACKED ARRAY [ 1 . . 4 ] OF CHAR; 


{trailing string for first 12-hour cycle} 
PACKED ARRAY [1.. 4] OF CHAR; 


{trailing string for last 12-hour cycle} 
CHAR; {time separator} 

CHAR; {trailing string for 24-hour cycle} 
CHAR; 

CHAR; 


CHAR; 


CHAR; 

CHAR; 


CHAR; 


CHAR; 

Byte; {255 if metric, 0 if not} 
INTEGER {version information} 


- “IntllPtr; 

■ “IntllRec; 

- PACKED RECORD 

days: 

months: 

suppress Day : 

longDateFmt: 

dayleading0: 

abbrLen: 

st0: 

stl : 

st2 : 

st3: 

st4 : 

intllVers : 
localRtn: 


END; 


ARRAY[ 1.. 7] OE STRING ( 15 ] ; {day names} 
ARRAY[ 1 . . 12] OF STRING[15]; {month names} 
Byte; {0 for day name, 255 for none} 
Byte; {order of long date elements} 
Byte; {255 for leading 0 in day number} 
Byte; {length for abbreviating names} 
PACKED ARRAY [1.. 4] OF CHAR; {strings } 
PACKED ARRAY [1.. 4] OF CHAR; { for } 

PACKED ARRAY fl.. 4} OF CHAR; { long } 
PACKED ARRAY [ 1 . . 4 ] OF CHAR; { date } 
PACKED ARRAY [U. 4] OF CHAR; { format} 
INTEGER; {version information} 

INTEGER {routine for localizing string } 
{ comparison; actually may be } 

{ longer than one integer} 


(shortDate, longDate, abbrevDate); 
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Routines 

PROCEDURE IUDateString (dateTime: Longlnt; form: DateForm; VAR result: 

Str255); 

PROCEDURE IUDatePString (dateTime: Longlnt; form: DateForm; VAR result: 

Str255; intlParam: Handle); 

PROCEDURE IUTimeString (dateTime: Longlnt; wantSeconds: BOOLEAN; VAR 

result: Str255); 

PROCEDURE IUTimePString (dateTime: Longlnt; wantSeconds: BOOLEAN; VAR 

result: Str255; intlParam: Handle); 

FUNCTION IUMetric : BOOLEAN; 

FUNCTION IUGetlntl (thelD: INTEGER) : Handle; 

PROCEDURE IUSetlntl (refNum: INTEGER; thelD: INTEGER; intlParam: 

Handle); 

FUNCTION IUCompString (aStr.bStr: Str255) : INTEGER; (Pascal only] 

FUNCTION IUMagString (aPtr.bPtr: Ptr; aLen.bLen: INTEGER) : INTEGER; ^ 
FUNCTION IUEqualString (aStr.bStr: Str255) : INTEGER; [Pascal only] 

FUNCTION IUMaglDString (aPtr.bPtr: Ptr; aLen.bLen: INTEGER) : INTEGER; 


Assembly-Language Information 


Constants 

; Currency format 

cu r r SymLe ad • EQU 

4 

;set if currency symbol leads 

currNegSym 

.EQU 

5 

;set if minus sign for negative 

currTrailingZ 

.EQU 

6 

;set if trailing decimal zeroes 

currLeadingZ 

.EQU 

7 

;set if leading integer zero 

; Order of short date 

elements 

mdy 

.EQU 

0 

; month day year 

dmy 

.EQU 

1 

;day month year 

ymd 

.EQU 

2 

;year month day 

; Short date 

format 



dayLeadingZ 

.EQU 

5 

;set if leading zero for day 

mntLeadingZ 

.EQU 

6 

;set if leading zero for month 

century 

.EQU 

7 

;set if century included 

; Time format 

secLeadingZ 

.EQU 

5 

;set if leading zero for seconds 

minLeadingZ 

.EQU 

6 

;set if leading zero for minutes 

hrLeadingZ 

.EQU 

7 

;set if leading zero for hours 
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; High-order byte of version information 


verUS 

.EQU 

0 

ver France 

.EQU 

1 

verBritain 

.EQU 

2 

ver Germany 

.EQU 

3 

verltaly 

.EQU 

4 

; Date form 

for IUDateString and IUDatePString 

shortDate 

.EQU 

0 ; short form of date 

long Date 

.EQU 

1 ;long form of date 

abbrevDate 

.EQU 

2 ; abbreviated long form 

International Resource 

0 Data Structure 


decimalPt 

thousSep 

listSep 

currSym 

currFmt 

dateOrder 

shortDateFmt 

dateSep 

timeCycle 

timeFmt 

mornStr 

eveStr 

time Sep 

timeSuf f 

metrlcSys 

intl0Vers 


Decimal point character 


Thousands separator 
List separator 
Currency symbol 
Currency format 
Order of short date 
Short date format 
Date separator 
0 if 24-hour cycle. 
Time format 
Trailing string for 
Trailing string for 
Time separator 
Trailing string for 
255 if metric, 0 if 
Version information 


elements 

255 if 12-hour 

first 12-hour cycle 
last 12-hour cycle 

24-hour cycle 
not 


International Resource 1 Data Structure 


days 

months 

suppressDay 

longDateFmt 

dayleading0 

abbrLen 

st0 

stl 

st2 

st3 

st4 

inti IVers 
localRtn 


Day names 
Month names 

0 for day name, 255 for none 
Order of long date elements 
255 for leading 0 in day number 
Length for abbreviating names * 
Strings for long date format 


Version information 
Comparison localization routine 
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Routine., Selectors 


Routine 

Select 

lUDatePString 

14 

IUDateString 

0 

IUGetlntl 

6 

lUMagIDString 

12 

IUMagString 

10 

IUMetric 

4 

IUSetlntl 

8 

IUTimePString 

16 

IUTimeString 

2 
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SUMMARY OF THE BINARY-DECIMAL CONVERSION PACKAGE 


Routines 


PROCEDURE NumToString (theNum: Long In t; VAR theString: Str255); 
PROCEDURE StringToNum (theString: Str255; VAR theNum: Longlnt); 


Assembly-Language Information 


Routine Selectors 


Routine Selector 

NumToString 0 

StringToNum 1 
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SUMMARY OF THE STANDARD FILE PACKAGE 


Constants 


CONST - putDIgID - -3999; {SFPutFlle dialog template ID} 

{ Item numbers of enabled items in SFPutFile dialog } 


putSave ” 1 ; 
putCancel ■ 2; 
putEject ■ 5; 
putDrive ■ 6; 
putName ■ 7 ; 


{Save button} 

{Cancel button} 

{Eject button} 

{Drive button} 

{editText item for file name} 


getDIgID * -4000; {SFGetFile dialog template ID} 

’{ Item numbers of enabled items in SFGetFile dialog } 


getOpen ■ 1 
getCancel * 3 
getEject “ 5 
get Drive ■ 6 
getNmList * 7 
getScroll ■ 8 


{Open button} 

{Cancel button} 

{Eject button} 

{Drive button} 

{user Item for file name list} 
{userltem for scroll bar} 




Data Types 

TYPE SFReply - RECORD 


good : 

BOOLEAN; 

copy: 

BOOLEAN; 

f Type : 

OSType ; 

vRefNum: 

INTEGER; 

version: 

INTEGER; 

fName: 

STRING [63] 

END; 



{FALSE if ignore command} 
{not used} 

{file type or not used} 
{volume reference number} 
{file's version number} 
{file name} 


SFTypeList - ARRAY [0..3] OF OSType; 


Routines 


PROCEDURE SFPutFile (where: Point; prompt: Str255; origName: Str255; 

dlgHook: ProcPtr; VAR reply: SFReply); 

PROCEDURE SFPPutFile (where: Point; prompt: Str255; origName: Str25S; 

dlgHook: ProcPtr; VAR reply: SFReply; dlglD: 
INTEGER; filterProc: ProcPtr); 

PROCEDURE SFGetFile (where: Point; prompt: Str255; flleFllter: 

ProcPtr; numTypes: INTEGER; typeList: SFTypeList; 
dlgHook: ProcPtr; VAR reply: SFReply); 
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PROCEDURE SFPGetFile (where: Point; prompt: Str255; flleFilter: 

ProcPtr; numTypes: INTEGER; typeList: SFTypeLlst; 
dlgHook: ProcPtr; VAR reply: SFReply; dig ID: 
INTEGER; filterProc: ProcPtr); 


DlgHook Function 

FUNCTION MyDlg (Item: INTEGER; theDlalog: DialogPtr) : INTEGER; 
FlleFilter Function 


FUNCTION MyFileFllter (paramBlock: ParmBlkPtr) : BOOLEAN; 


Standard 

SFPutFile Items 


Item number 

Item 

Standard display rectangle 

1 


Save button 

(12, 74, 82, 92) 

2 


Cancel button 

(114, 74, 184, 92) 

3 


Prompt string (statText) 

(12, 12, 184, 28) 

4 


Userltem for disk name 

(209 , 16, 295, 34) 

5 


Eject button 

(217, 43, 287 , 61) 

6 


Drive button 

(217, 74, 287, 92) 

7 


EditText item for file name 

(14, 34, 182, 50) 

8 


Userltem for gray line 

(200, 16, 201, 88) 

Resource 

IDs 

of SFPutFile Alerts 



Alert 

Resource ID 

Existing file 

-3996 

Locked disk 

-3997 

System error 

-3995 

Disk not found 

-3994 


Standard 

SFGetFile Items 


Item number Item 

Standard display rectangle 

i 

Open button 

(152, 28, 232, 46) 

2 

Invisible button 

(1152, 59, 1232, 77) 

3 

Cancel button 

(152, 90, 232, 108) 

4 

Userltem for disk name 

(248, 28, 344, 46) 

5 

Eject button 

(256, 59, 336, 77) 

6 

Drive button 

(256, 90, 336, 108) 

7 

Userltem for file name list 

(12, 11, 125, 125) 

8 

Userltem for scroll bar 

(124, 11, 140, 125) 

9 

Userltem for gray line 

(244, 20, 245, 116) 

10 

Invisible text (statText) 

(1044, 20, 1145, 116) 
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Assembly-Language Information 


Constants 


putDIgID 

.EQU 

-3999 

; SFPutFile dialog template 

ID 

; Item numbers 

of enabled 

items 

in SFPutFile dialog 


putSave 

.EQU 

1 

;Save button 


putCancel 

.EQU 

2 

;Cancel button 


putEject 

.EQU 

5 

; Eject button 


put Drive 

.EQU 

6 

; Drive button 


putName 

.EQU 

7 

;editText item for file name 

get Dig ID 

.EQU 

-4 000 

; SFGetFile dialog template 

ID 

; Item numbers 

of enabled 

Items 

in SFGetFile dialog 


getOpen 

.EQU 

1 

;0pen button 


getCancel 

.EQU 

3 

; Cancel button 


getEject 

.EQU 

5 

;Eject button 


getDrive 

.EQU 

6 

{Drive button 


getNmList 

.EQU 

7 

;userl£em for file name list 

getScroll 

.EQU 

8 

{userltem for scroll bar 



Reply Record Data Structure 


rGood 

rType 

rVolume 

rVersion 

rName 


FALSE if ignore command 
File type 

Volume reference number 
File's version number 
File name 




Routine Selectors 


Routine 

SFGetFile 

SFPGetFile 

SFPPutFile 

SFPutFile 


Selector 

2 

4 

3 

1 




5/7 / 84 Hacker-Rose 


/PACKAGES/PACK. S 



SUMMARY OF THE DISK INITIALIZATION PACKAGE 


51 




SUMMARY OF THE DISK INITIALIZATION PACKAGE 


Routines 


PROCEDURE DILoad; 
PROCEDURE DIUnload; 
FUNCTION DIBadMount 
FUNCTION DIFormat 
FUNCTION DIVerify 
FUNCTION DIZero 


(where: Point; evtMessage: 
(drvNum: INTEGER) : OsErr; 
(drvNum: INTEGER) : OsErr; 
(drvNum: INTEGER; volName: 


Longlnt) 


Str255) 


: INTEGER; 


OSErr; 


Assembly-Language Information 


Routine Selectors 


Routine 

DIBadMount 

DIFormat 

DILoad 

DIUnload 

DIVerify 

DIZero 


Selector 

0 

6 

2 

4 

8 

10 


Result Codes 




Name 

Value 

Meaning 

badMDBErr 

-60 

Bad master directory block 

extFSErr 

-58 

External file system 

firstDskErr 

-84 

First of the range of low-level disk errors 

ioErr 

-36 

Disk I/O error 

lastDskErr 

-64 

Last of the range of low-level disk errors 

mFulErr 

-41 

Memory full 

no Err 

0 

No error 

noMacDskErr 

-57 

Not a Macintosh disk 

nsDrvErr 

-56 

No such drive 

paramErr 

-50 

Bad drive number 

volOnLinErr 

-55 

Volume already on-line 
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GLOSSARY 

ligature: A character that combines two letters* 

list separator: The character that separates numbers, as when a list 
of numbers is entered by the user. 

package: A set of data structures and routines that's stored as a 
resource and brought into memory only when needed* 

routine selector: An integer that's pushed onto the stack before the 
_PackN macro is invoked, to identify which routine to execute. (N is 
the resource ID of a package; all macros for calling routines in the 
package expand to invoke _PackN. ) 

thousands separator: The character that separates every three digits 
to the left of the decimal point. 
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COMMENTS? 

Macintosh User Education encourages your comments on this manual. 

- What do you like or dislike about it? 

- Were you able to find the information you needed? 

- Was it complete and accurate? 

- Do you have any suggestions for improvement? 

Please send your comments to the author (indicated on the coyer 
page) at 10460 Bandley Drive M/5 3-G, Cupertino CA 95014. 

Mark up a copy of the manual or note your remarks separately. 

(We'll return your marked-up copy if you like.) 


Thanks for your help! 



The MacPaint Document Format 

by Bill Atkinson 

MacPaint documents are easy to read and write, and have become a 
standard interchange format for full-page bitmap Images on Macintosh. 
Their internal format is described here to aid program developers in 
generating and reading MacPaint documents. 

MacPaint documents use only the data fork of the file system; the resource 
fork is not used and may be ignored. The data fork contains a 512 byte 
header and then the compressed data representing a single bitmap of 576 
pixels wide by 720 pixels tall. At 72 pixels per inch, this bitmap occupies 
the full 8 by 10 inch printable area of the Imagewriter printer page. 

HEADER: 

The first 512 bytes of the document form a header with a 4 byte version 
number (default - 2), then 38*8 - 304 bytes of patterns, then 204 unused 
bytes reserved for future expansioa If the version number is zero, the 
rest of the header block is ignored and default patterns are used, so 
programs generating MacPaint documents can simply write out 512 bytes 
of zero as the document header. Most programs which read MacPaint 
documents can simply skip over the header when reading. 

BITMAP: 

Following the header are 720 compressed scanlines of data which form the 
576 wide by 720 tall bitmap. Without compression, this bitmap would 
occupy 51840 bytes and chew up disk space pretty fast; typical MacPaint 
documents compress to about 10 Kbytes using the PackBIts procedure in 
the Macintosh ROM to compress runs of equal bytes within each scanline. 
The bitmap part of a MacPaint document is simply 720 times the output of 
PackBits with 72 bytes input. 



WRITING SAMPLE: 


To write out a 576 by 720 bitmap which is contained in memory, the 
following fragment of code could be used: 

TYPE dfSkBlock - PACKED ARRAYl I ..5 1 21 OF QDBy te; 

VAR srcPtr,dstPtr. QDPtr; 
dstBuf: dtskBlock; 

dstBytes: INTEGER; 

( write the header, all zeros } 

FOR I :- I to 512 00 dStBuflil :« 0; 

WriteOata(dstF lie, ©dstBuf, 5 1 2); 

( Compress each scanline and write it ) 
srcPtr :■ srcBits.baseAddr; 

FOR scanline 1 to 720 DO 
BEGIN 

dstPtr :- ©dstBuf; 

PackBits(srcPtr,dstPtr,72); 
dstBytes ORD(dstPtr) - ORD( ©dstBuf); 
WrtteData(dstF11e,©dstBuf, dstBytes); 

END; 


( bumps both ptrs } 

( calc packed size ) 

( write packed data } 


READING SAMPLE: 


CONST srcBlocks *2; (at least 2, bigger makes It faster } 
srcSize - 1024; ( 512 * srcBlocks } 

TYPE dlskBlock - PACKED ARRAY! I ..5 1 2] OF QDByte; 

VAR srcBuf: ARRAY! I ..srcBlocks] OF dlskBlock; 
srcPtr,dstPtr QDPtr; 

( skip the header ) 

ReadData(srcF I le, ©srcBuf ,5 1 2); 

! prime srcBuf ] 

ReadData(srcF I le, ©srcBuf ,srcSize); 

( unpack each scanline Into dstBits, reading more source as needed ) 
srcPtr ©srcBuf; 
dstPtr dstBits.baseAddr; 

FOR scanLlne :■ I to 720 DO 
BEGIN 

UnPackBlts(srcPtr,dstPtr,72); ( bumps both ptrs ) 

( time to read next chunk of packed source ? ] 

IF ORD(srcPtr) > ORD( ©srcBuf) ♦ srcSize - 512 THEN 
BEGIN 

srcBuf! 1 1 srcBuflsrcBlocks]; ( move up last block } 
ReadData(srcFf le^srcBuffcLsrcSIze-S 1 2 ); 
srcPtr :* Pointer(ORD(srcPtr) - srcSize ♦ 512)* 

END; 

END; 
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ABSTRACT 


This manual describes the Memory Manager, the part of the Macintosh 
Operating System that controls the dynamic allocation of memory space 
on the heap. 
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ABOUT THIS MANUAL 


This manual describes the Memory Manager, the part of the Macintosh 
Operating System that controls the dynamic allocation of memory space 
on the heap* *** Eventually it will become part of a larger manual 
describing the entire Operating System. *** 

(eye) 

This manual describes version 7, the final, ’’frozen” 
version of the Macintosh ROM. Earlier versions may not 
work exactly as described here. *** There may someday be 
one or more special, RAM-based versions of the Memory 
Manager for software development purposes, doing more 
extensive error checking or gathering statistics on a 
program’s memory usage. This manual describes the ROM- 
based version only. *** 

Like all Operating System documentation, this manual is intended for 
both Pascal and assembly-language programmers. All readers are assumed 
to be familiar with Lisa Pascal; information of interest only to 
assembly-language programmers is isolated and labeled so that Pascal 
programmers can conveniently skip it. Whichever is your preferred 
language, please bear with occasional remarks addressed solely to the 
other group. 

The manual begins with an introduction to the Memory Manager and what 
it's used for. It then discusses some basic concepts behind the Memory 
Manager's operation: how blocks of memory are allocated within the 
heap and how the allocated blocks are referred to by programs that use 
them. Following this is a discussion of the internal data structures 
that the Memory Manager uses to find its way around in the heap. 

A section on using the Memory Manager introduces its routines and tells 
how they fit into the flow of your application program. This is 
followed by detailed descriptions of all Memory Manager procedures and 
functions, their parameters, calling protocol, effects, side effects, 
and so on. 

Following these descriptions are sections that will not be of interest 
to all readers. Special information is given on unusual techniques 
that you may find useful in working with the Memory Manager and on how 
to use it from assembly-language programs. 

Finally, there is a quick-reference summary of the Memory Manager’s 
data structures and routines, along with a glossary of terms used in 
this manual. 
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about the memory manager 

Using the Memory Manager, your program can maintain one or more 
independent areas of heap memory (called heap zones ) and use them to 
allocate blocks of memory of any desired size* Unlike stack space, 
which is always allocated and released in strict LIFO (last-in-f irst*- 
out) order, blocks on the heap can be allocated and released in any 
order, according to your program's needs. So instead of growing and 
shrinking in an orderly way like the stack, the heap tends to become 
fragmented into a patchwork of allocated and free blocks, as shown in 
Figure 1. The Memory Manager does all the necessary "housekeeping" to 
keep track of the blocks as it allocates and releases them. 


Heap zone 



Relocatable blocks 

Nonrelocatable blocks 


Free blocks 




Figure i. A. Fragmented Heap 


all memory allocation is performed within a particular heap zone* ihr: 
Memory Manager always maintains at least two heap zones s a system heag_ 
zone , reserved for the system's own use, and an application heap zone 
for use by your program. The system heap zone is initialized to 16K 
bytes when the system is started up. Objects in this zone remain 
allocated even when one application terminates and another is launched* 
The application heap zone is automatically reinitialized at the start 
of each new application program, and the contents of any previous 
application zone are lost. The initial size of the application zone is 
6K bytes, but it can grow as needed to create more heap space while the 
program is running. Your program can create additional heap zones it 
it chooses, either by subdividing this original application zone or by 
allocating space on the stack for more heap zones. 


(hand) 


In this manual, unless otherwise stated 
"application heap zone" (or just "appii 


the term 
srioti zone") 
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always refers to the original application heap zone 
provided by the system, before any subdivision. 

Various parts of the Macintosh Operating System and Toolbox also use 
space in the application heap zone. For instance, the actual machine- 
language code of your program resides in the application zone, in space 
reserved for it at the request of the Segment Loader. Similarly, the 
Resource Manager requests space in the application zone to hold 
resources it has read into memory from a resource file. Toolbox 
routines that create new entities of various kinds, such as NewWindow, 
NewControl, and NewMenu, implicitly call the Memory Manager to allocate 
the space they need* 

At any given time, there is exactly one current heap zone , to which 
most Memory Manager operations implicitly apply. You can control which 
heap zone is current by calling a Memory Manager procedure. Whenever 
the system needs to access its own (system) heap zone, it saves the 
setting of the current heap zone and restores it later, so that the 
operation is transparent to your program. 

Space within a heap zone is divided up into contiguous pieces called 
blocks . The blocks in a zone fill it completely: every byte in the 
zone is part of exactly one block, which may be either allocated 
(reserved for use by your program or by the system) or free (available 
for allocation). Each block has a block header containing information 
for the Memory Manager's own use, followed by the block's contents , the 
area available for use (see Figure 2). There may also be some unused 
bytes at the end of the block, beyond the end of the contents. 


Assembly-language note : Blocks are always aligned on even word 
boundaries, so you can access them with word (.W) and long-word 
(.L) Instructions. 
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Figure 2. A Block 


A block can be of any size, limited only by the size of the heap zone 
itself. What’s inside the block is of no concern to the Memory 
Manager: it may contain data being used by your program, executable 

code forming part of the program itself, resource information read from 
a resource file, or anything else that may be appropriate. To the 
Memory Manager, it's just a block of a certain size. 

(hand) 

Don’t confuse the blocks manipulated by the Memory 

Manager with disk blocks, which are always 512 bytes 

long. 

An allocated block may be relocatable or nonrelocatable ; if 
relocatable, it may be locked or unlocked ; if unlocked, it may be 
purgeable or unpurgeable . Relocatable blocks can be moved around 
within the heap zone to create space for other blocks; nonrelocatable 
blocks can never be moved. These are permanent properties of a block 
that can never be changed once the block is allocated. The remaining 
attributes (locked and unlocked, purgeable and unpurgeable) can be set 
and changed as necessary. Locking a relocatable block prevents it from 
being moved, but only temporarily: you can unlock the block at any 
time, again allowing the Memory Manager to move it. Making a block 
purgeable allows the Memory Manager to remove it from the heap zone, if 
necessary, to make room for another block. (Purging of blocks is 
discussed further below under ’’How Heap Space Is Allocated”.) A newly 
allocated block is initially unlocked and unpurgeable. 


CONFIDENTIAL 
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POINTERS AND HANDLES 


Relocatable and nonrelocatable blocks are referred to in different: 
ways: nonrelocatable blocks by pointers, relocatable blocks by handles 
(discussed below). When the Memory Manager allocates a new 
nonrelocatable block, it returns a pointer to the block. Thereafter, 
whenever you need to refer to the block, you use this pointer. Like 
any other pointer, it’s simply a memory address: that of the first 
byte in the block’s contents (see Figure 3). You can make as many 
copies of this pointer as you like. Since the block they point to can 
never be moved within its heap zone, you can rely on all copies of the 
pointer to remain correct. They will continue to point to the block 
for as long as the block remains allocated. 


Heap zone 



Figure 3. A Pointer to a Nonrelocatable Block 


Relocatable blocks don’t share this property, however. If necessary to 
make room for some other block, the Memory Manager can move a 
relocatable block at any time to a new location in its heap zone. This 
would leave any pointers you might have to the block pointing to the 
wrong place in memory, or '’dangling". Dangling pointers can be very 
difficult to diagnose and correct, since their effects typically aren’t 
discovered until long after the pointer is left dangling. 

To help avoid dangling pointers, the Memory Manager maintains a single 
master pointer to each relocatable block, allocated from within the 
same heap zone as the block itself. The master pointer is created at 
the same time as the block and set to point to it. What you get back 
from the Memory Manager when you allocate a relocatable block is a 
pointer to the master pointer, called a handle to the block (see Figure 
4). From then on, you always use this handle to refer to the block. 

If the Memory Manager later has to move the block, it has only to 
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update the master pointer to point to the block’s new location; the 
master pointer itself is never moved. Since all copies of the handle 
point to the block by double indirection through this same master 
pointer, they can be relied on not to dangle, even after the block has 
been moved. 


Heap 2one 



Handle 


Muter pointer 
Relocatable block 




Figure 4. A Handle to a Relocatable Block 


(eye) 

To maintain the integrity of the memory allocation 
system, always use the Memory Manager routines provided 
(or other Operating System or Toolbox routines that call 
them) to allocate and release space on the heap. Don’t 
use the Pascal standard procedures NEW and DISPOSE. 

*** Eventually the versions of these routines in the 
Pascal Library will be changed to work through the Memory 
Manager. *** 




HOW HEAP SPACE IS ALLOCATED 

The Memory Manager allocates space in a heap zone according to a first 
fit" strategy. When you ask to allocate a block of a certain size, the 
Memory Manager scans the current heap zone looking for a place to put 
the new block. For relocatable blocks, it looks for a free block of at 
least the requested size, scanning forward from the end of the last 
block allocated and "wrapping around" if necessary from the end of the 
zone to the beginning. (Nonrelocatable blocks are handled a bit 
differently, as described below.) As soon as it finds a free block big 
enough, it allocates the requested number of bytes from that block. 

That is, it uses the first free block it finds that’s big enough to 
satisfy the request, instead of continuing to search for a better fit. 
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If a single free block can't be found that's big enough, the Memory 
Manager tries to create one by compacting the heap zone: moving 
allocated blocks together in order to collect the free space into a 
single larger free block (see Figure 5). Only relocatable, unlocked 
blocks can be moved. The compaction continues until either a free 
block of at least the requested size has been created or the entire 
heap zone has been compacted. 


Hnp zone 




*» # » , * , **#% , »% , *W%***#*«%\*»^**»***»****%%* •* 















Heap zone 


M Relocatable blocks 
| Nonrelocatable blocks 
| 1 Free blocks 



Before 


After 


Figure 5. Heap Compaction 


Notice that nonrelocatable blocks (and relocatable ones that are 
temporarily locked) tend to interfere with the compaction process by 
forming immovable "islands" in the heap. This can prevent free blocks 
from being collected together and lead to fragmentation of the 
available free space, as shown in Figure 6. To minimize this problem, 
the Memory Manager tries to keep all the nonrelocatable blocks together 
at the beginning of the heap zone. When you allocate a nonrelocatable 
block, the Memory Manager will do everything in its power to make room 
for the new block at the lowest available position in the zone, 
including moving other blocks upward, expanding the zone, or purging 
blocks from it (see below). 


10/10/83 Chernicoff 


CONFIDENTIAL 


/MEM. MGR/MEMORY. 2 




10 


Memory Manager Programmer’s Guide 


I loop zone 



Relocatable blocks 


Norrelocatable blocks 


Free blocks 


Heap 2one 



Before 


After 


Figure 6, Fragmentation of Free Space 


If the Memory Manager still can’t satisfy the allocation request after 
compacting the entire heap zone, it next tries expanding the zone by 
the requested number of bytes, rounded upward to the nearest IK. Only 
the original application zone can be expanded, and only up to a certain 
limit (discussed more fully under ’’The Stack and the Heap”, below)* If 
any other zone is current, or if the application zone has already 
reached or exceeded its limit, this step is skipped* 

Next the Memory Manager tries to free space by purging blocks from the 
zone* Only relocatable blocks can be purged, and then only if they’re 
explicitly marked as unlocked and purgeable* Purging a block removes 
it from its heap zone and frees the space it occupies* The block’s 
master pointer is set to NIL, but the space occupied by the master 
pointer itself remains allocated* Any handles to the block now point 
to a NIL master pointer, and are said to be empty* If your program 
later needs to refer to the purged block, it can detect that the handle 
has become empty and ask the Memory Manager to reallocate the block* 
This operation updates the original master pointer, so that all handles 
to the block are left referring correctly to its new location (see 
Figure 7)* 

(eye) 

Reallocating a block only recovers the space it occupies, 
not its contents* Any information the block contains is 
lost when the block is purged* It’s up to your program 
to reconstitute the block's contents after reallocating 
it. 
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Heap zone 



Before purging 


Heap zone 


Handle 



Master pointer 



Heap zone 



After reallocating 

Figure 7. Purging and Reallocating a Block 
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Finally , if all else fails , the Memory Manager calls the grow zone 
function , if any, for the current heap zone* This is an optional 
routine that you can provide to take any last-ditch measures your 
program may have at its disposal to try to free some space in the zone* 
The term "grow zone function" is misleading, since the function doesn't 
actually attempt to "grow" (expand) the zone* Rather, its purpose is 
to try to create additional free space within the existing zone (such 
as by purging blocks that were previously marked unpurgeable) or reduce 
the fragmentation of existing free space (such as by unlocking 
previously locked blocks)* The Memory Manager will call the grow zone 
function repeatedly, compacting the heap again after each call, until 
either it finds the space it's looking for or the grow zone function 
reports that it can offer no further help* In the latter case, the 
Memory Manager will give up and report that it's unable to satisfy your 
allocation request* 


THE STACK ANT) THE HEAP 




The application heap zone and the application stack share the same area 
in memory, growing toward each other from opposite ends (see Figure 8)* 
Naturally it would be disastrous for either to grow so far that it 
collides with and overwrites the other* To help prevent such 
collisions, the Memory Manager enforces a limit on how far the 
application heap zone can grow toward the stack* \oxiv program can set 
this application heap limit to control the allotment of available space 
betwen the stack and the heap* 


Applied ion heap 



F re© space 


Stack 


Lov memory 





Figure The brack and the Heap 
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The application heap limit marks the boundary between the space 
available for the application heap zone and that reserved exclusively 
for the stack. At the start of each application program, the limit is 
initialized to allow 8K bytes for the stack. Depending on your 
program's needs, you can then adjust the limit to allow more heap space 
at the expense of the stack or vice versa. 

Notice, however, that the limit applies only to expansion of the heap; 
it has no effect on how far the stack can expand. That is, although 
the heap can never expand beyond the limit into space reserved for the 
stack, there's nothing to prevent the stack from crossing the boundary 
and encroaching on space allotted for heap expansion— or even from 
overwriting part of the heap itself. It's up to you to set the limit 
low enough to allow for the maximum stack depth your program will ever 
need. 

(hand) 

Regardless of the limit setting, the application zone is 
never allowed to grow to within IK of the current end of 
the stack. This gives a little extra protection in case 
the stack is approaching the boundary or has crossed over 
onto the heap's side, and allows some safety margin for 
the stack to expand even further. 

To help detect collisions between the stack and the heap, a "stack 
sniffer" routine is run sixty times a second, during the Macintosh's 
vertical retrace interrupt. This routine compares the current ends of 
the stack and the heap and opens an alert box on the screen in case of 
a collision. The stack sniffer can't prevent collisions, only detect 
them after the fact: a lot of computation can take place in a sixtieth 
of a second. In fact, the stack can easily expand into the heap, 
overwrite it, and then shrink back again before the next activation of 
the stack sniffer, escaping detection completely. The stack sniffer is 
useful mainly during software development; the alert box it displays 
can be confusing to your program's end user. Its purpose is to warn 
you, the programmer, that your program's stack and heap are colliding, 
so that you can adjust the heap limit to correct the problem before the 
user ever encounters it. 


UTILITY DATA TYPES 


The Memory Manager includes a number of type definitions for general- 
purpose use. For working with pointers and handles to allocated 
blocks, there are the following definitions: 

TYPE SignedByte = -128.. 127; 

Byte 3 0 . • 255 ; 

Ptr * ^SignedByte; 

Handle 3 ~Ptr; 

SignedByte stands for an arbitrary byte in memory, just to give Ptr and 
Handle something to point to. You can define a buffer of bufSize 
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untyped memory bytes as a PACKED ARRAY [l..bufSize] OF SignedByte. 

Byte is an alternative definition that treats byte-length data as 
unsigned rather that signed quantities. 

Because of Pascal's strong typing rules, you can't directly assign a 
value of type Ptr to a variable of some other pointer type. Instead, 
you have to use the Lisa Pascal functions ORD and POINTER to convert 
the pointer to an integer address and then back to a pointer. For 
example, after the declarations 

VAR aPtr: Ptr; 

somethingElse : *Thing ; 

you can make somethingElse point to the same object as aPtr with the 
assignment 

somethingElse PO INTER( ORD( aPt r ) ) 

This works because POINTER returns a generalized "pointer to anything" 
(like the Pascal pointer constant NIL) that can be assigned to any 
variable of pointer type or supplied as an argument value for any 
routine parameter of pointer type. 

Type ProcPtr, defined as 

TYPE ProcPtr * Ptr; 

is useful for treating procedures and functions as data objects. If 
aProcPtr is a variable of type ProcPtr and myProc is a procedure (or 
function) defined in your program, you can make aProcPtr point to 
myProc by using Lisa Pascal's @ operator: 

aProcPtr 2 * @myProc 

Like the POINTER function, the <3 operator produces a "pointer to 
anything". Using it, you can assign procedures and functions to 
variables of type ProcPtr, embed them in data structures, and pass them 
as arguments to other routines. Notice, however, that a ProcPtr 
technically points to a SignedByte, not an actual routine. As a 
result, there's no way in Pascal to access the underlying routine in 
order to call it. Only routines written in assembly language (such as 
those in the Operating System and the Toolbox) can actually call the 
routine designated by a ProcPtr. 

For specifying the sizes of blocks on the heap, the Memory Manager 
defines a special type called Size: 

TYPE Size * Longlnt; 

All Memory Manager routines that deal with block sizes expect 
parameters of type Size or return them as results. To specify a size 
bigger than any existing block, you can use the constant raaxSize: 
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CONST maxSize * $800000; 

This is an enormous value, equivalent to 8 megabytes or 8,388,608 bytes 
— more than forty times the Macintosh's total memory capacity! 


MEMORY MANAGER DATA STRUCTURES 

This section contains detailed information on the Memory Manager's 
internal data structures. You won't need this information if you're 
just using the Memory Manager routinely to allocate and release blocks 
of memory from the application heap zone. The details are included 
here for programmers with unusual needs (or who are just curious about 
how the Memory Manager works). 


Structure of Heap Zones 

Each heap zone begins with a 52-byte zone header and ends with a 12- 
byte zone trailer (see Figure 9). The header contains all the 
information the Memory Manager needs about that heap zone; the trailer 
is just a minimum-size free block (described in the next section) 
placed at the end of the zone as a marker. All the remaining space 
between the header and trailer is available for allocation. 


Heap 2one 



Figure 9. Structure of a Heap Zone 


In Pascal, a heap zone is defined as a zone record of type Zone, 
reflecting the structure of the zone header. It's always referred to 
with a zone pointer of type THz ("the heap zone"): 
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TYPE THz - “Zone ; 
Zone =* RECORD 


bkLim: 

Ptr ; 

purgePtr : 

Ptr ; 

hFstFree : 

Ptr; 

zcbFree : 

Longlnt 

gzProc : 

ProcPtr 

moreMasc : 

INTEGER 

flags : 

INTEGER 

cntRel : 

INTEGER 

maxRel : 

INTEGER 

cntNRel : 

INTEGER 

maxNRel : 

INTEGER 

cnt Empty : 

INTEGER 

cntHandles : 

INTEGER 

minCBFree : 

Longlnt 

purgeProc: 

ProcPtr 

sparePtr : 

Ptr; 

allocPtr : 

Ptr; 

heapData: 

INTEGER 


END; 


(eye) 

The fields of Che zone header are for Che Memory 
Manager's own inCernal use. You can examine Che conCenCs 
of Che zone's fields, buC in general ic doesn'c make 
sense for your program Co Cry Co change Chem. The few 
excepCions are noced below in Che discussions of Che 
specific fields. 

BkLim is a poinCer Co Che zone's Crailer block. Since Che Crailer is 
Che lasC block in Che zone, chis consCiCuCes a limlc poinCer Co Che 
memory byCe following Che lasc byCe of usable space in Che zone. 

PurgePCr and allocPCr are "roving poinCers" inco Che heap zone ChaC Che 
Memory Manager mainCains for iCs own infernal use. When scanning Che 
zone for a free block Co saCisfy an allocaCion requesc, Che Memory 
Manager begins aC Che block poinCed Co by allocPCr inscead of always 
sCarCing from Che beginning of Che zone. When purging blocks from Che 
zone, iC scarfs from Che block poinCed Co by purgePCr. 

HFsCFree is a poinCer Co Che firsc free mascer poinCer in Che zone. 
Inscead of just allocacing space for one masCer poinCer each cime a 
relocaCable block is creaCed, Che Memory Manager "preallocaCes" several 
masCer poinCers aC a cime, Chemselves forming a nonrelocaCable block 
wichin Che zone. The moreMasC field of Che zone record Cells Che 
Memory Manager how many masCer poinCers aC a Cime Co preallocaCe for 
Chis zone. MasCer poinCers for Che syscem heap zone are allocaCed 32 
aC a cime; for Che applicaCion zone, 64 aC a cime. For ocher heap 
zones, you specify Che value of moreMasc when you creace Che zone. 

All masCer poinCers ChaC are allocated but not currently in use are 
linked together into a list beginning in the hFstFree field. When you 
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allocate a new relocatable block, the Memory Manager removes the first 
available master pointer from this list, sets it to point to the new 
block, and returns its address to you as a handle to the block. (If 
the list is empty, it allocates a fresh block of moreMast master 
pointers, uses one of them for the new relocatable block, and adds the 
rest to the list.) When you release a relocatable block, its master 
pointer isn't released, but linked onto the beginning of the list to be 
reused. Thus the amount of space devoted to master pointers can 
increase, but can never decrease unless the zone is reinitialized (for 
example, at the start of a new application program). 

The zcbFree field always contains the number of free bytes remaining in 
the zone ("zcb" stands for "zone count of bytes")* As blocks are 
allocated and released, the Memory Manager adjusts zcbFree accordingly. 
This number represents an upper limit on the size of block you can 
allocate from this heap zone* 

(eye) 

It may not actually be possible to allocate a block as 
big as zcbFree bytes* As space in a heap zone becomes 
fragmented, the free bytes typically don't remain 
contiguous but become scattered throughout the zone* 

Because nonrelocatable and locked blocks can't be moved, 
it isn't always possible to collect all the free space 
into a single block by compaction. (Even if the zone 
contains only relocatable blocks, the master pointers to 
these blocks are themselves nonrelocatable "islands" that 
can interfere with the compaction process*) So the 
maximum— size block you can actually allocate from the 
zone may be appreciably smaller than zcbFree bytes. 

The gzProc field is a pointer to the zone's grow zone function, or NIL 
if there is none. You supply this pointer when you create a new heap 
zone and can change it at any time with the SetGrowZone procedure. The 
system and application heap zones initially have no grow zone function. 

Flags contains a set of flag bits strictly for the Memory Manager's 
internal use; your program should never need to access this field. 

CntRel, maxRel, cntNRel, maxNRel, cntEmpty, cntHandles, and minCBFree 
are not used by the ROM-based version of the Memory Manager* *** These 
fields are reserved for eventual use by a special RAM— based version 
that will gather statistics on a program's memory usage within each 
heap zone* CntRel and cntNRel will be used to count, respectively, the 
number of relocatable and nonrelocatable blocks currently allocated 
within the zone* MaxRel and maxNRel will record the "historical 
maximum" values attained by cntRel and cntNRel since the program was 
started. CntEmpty will count the current number of empty master 
pointers, cntHandles the total number of master pointers currently 
allocated. MinCBFree will record the historical minimum number of free 
bytes in the zone* *** 

PurgeProc is a pointer to the zone's purge warning procedure (sometimes 
called a "purge hook"), or NIL if there is none* The Memory Manager 
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will call this procedure whenever it purges a block from the zone. You 
can "install" a purge warning procedure in this field to do optional 
housekeeping such as writing out a block's contents to a disk file 
before it's purged. In fact, this is exactly the way the Resource 
Manager keeps the contents of resources up to date if they re changed 
by your program. If you want to install your own purge hook, you have 
to be very careful not to interfere with the one the Resource Manager 
may have installed; see "Special Techniques", later in this manual, for 
further details. 

SparePtr is an extra field included in the zone header for possible 
future expansion. 

The last field of a zone record, heapData, is a dummy field marking the 
beginning of the zone's usable memory space. HeapData nominally 
contains an integer, but this integer has no significance in itsel -- 
it's just the first two bytes in the block header of the first block in 
the zone. The purpose of the heapData field is to give you a way o 
locating the effective beginning of the zone. For example, if myZone 
is a zone pointer, then 

@( my Zone"*. heapData) 

is a pointer to the first usable byte in the zone, just as 
myZone * « bkLim 

is a limit pointer to the byte following the last usable byte in the 
zone. 


Structure of Blocks — — 

Every memory block in a heap zone, whether allocated or free, has a 
block header that the Memory Manager uses to find its way around in the 
zone. Block headers are completely transparent to your program. All 
pointers and handles to allocated blocks point to the beginning of the 
block's contents, following the end of the header. Similarly, all 
block sizes seen by your program refer to the block s logical size (the 
number of bytes in its contents) rather than its physical s^ze (the 
number of bytes it actually occupies in memory, including the header 
and any unused bytes at the end of the block). 

Since your program shouldn't normally have to deal with block headers 
directly, there's no Pascal record type defining their structure. 

(It's possible to access block headers in assembly language, but be 
sure you know what you're doing!) A block header consists of 8 bytes, 
as shown in Figure 10. 
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31 


24 23 


0 


Tag byte 

Physical block size 






/ Relocatable block: Relative handle 

L— 1 \ Nonrelocatable block: Pointer to heap zone 
l Free block: Unused 


Figure 10. Block Header 


The first byte of the block header is the tag byte, discussed in detail 
below. The next 3 bytes contain the block's physical size in bytes. 
Adding this number to the block's address gives the address of the next 
block in the zone. 

The contents of the second long word (4 bytes) in the block header 
depend on the type of block. For relocatable blocks , it contains the 
block's relative handle : a pointer to the block's master pointer, 
expressed as an offset relative to the start of the heap zone rather 
than as an absolute memory address. Adding the relative handle to the 
zone pointer produces a true handle for this block. For nonrelocatable 
blocks, the second long word of the header is just a pointer to the 
block's zone. For free blocks, these 4 bytes are unused. 


7 6 5 4 3 

2 

1 0 

> 

1 

i j ! 

i i i 

| 





Size correction 
Unused 


Tag 


Figure 11. Tag Byte 


The tag byte consists of a 2-bit tag , 2 unused bits, and a 4-bit size 
correction , as shown in Figure 11. The tag identifies the type of 
block: 
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Tag. 

Block type 

00 

Free 

01 

Nonrelocatable 

10 

Relocatable 


(A tag value of il is invalid.) 

The size correction is the number of unused bytes at the end of the 
block, beyond the end of the block’s contents. It’s equal to the 
difference between the block’s logical and physical sizes, excluding 
the 8 bytes of overhead for the block header: 

sizeCorrection =* physicalSize - logicalSize - 8 


There are several reasons why a block may contain such unused bytes: 

- The Memory Manager allocates space only in whole 16-bit words 
that is, in even numbers of bytes. If the block's logical size is 
odd, an extra, unused byte is added at the end to keep the 
physical size even. 

- Earlier versions of the Memory Manager used a block header of 12 
bytes Instead of 8. Although the header is now only 8 bytes long, 
the Memory Manager still enforces a minimum size of 12 bytes per 
block for compatibility with these earlier versions. If the 
logical size of a block is less than 4, enough extra bytes are 
allocated at the end of the block to bring its physical size up to 
12 . 


- The 12-byte minimum applies to all blocks, free as well as 

allocated. If allocating the required number of bytes from a free 
block would leave a fragment of fewer than 12 free bytes, the 
leftover bytes are included unused at the end of the newly 
allocated block instead of being returned to free storage. 

Putting all this together, the minimum overhead required for each 
allocated block is 8 bytes for the block header, plus an additional 4 
bytes for the master pointer if the block is relocatable. The maximum 
possible overhead is 26 bytes, for a relocatable block with a logical 
size of 0 being allocated from a free block of 22 bytes: 8 bytes for 
the header, 4 for the master pointer, 4 to satisfy the 12-byte minimum, 
and a leftover fragment of 10 free bytes that’s too small to return to 
free storage. 


Structure of Master Pointers _ 

The master pointer to a relocatable block has the structure shown in 
Figure 12. The low-order 3 bytes of the long word contain the address 
of the block's contents. The high-order byte contains some flag bits 
that specify the block's current status. Bit 7 of this byte is the 
lock bit (1 if the block is locked, 0 if it's unlocked); bit 6 is the 
purge bit (1 if the block is purgeable, 0 if it’s unpurgeable). Bit 5 
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is used by the Resource Manager to identify blocks containing resource 
information for special treatment; such resource blocks are marked by a 
1 in this bit. 

(eye) 

Before attempting to compare one master pointer with 
another or perform any arithmetic operation on it, don't 
forget to strip off the flag bits in the high-order byte. 


' ’ 


7 6 5 4 3 2 1 0 


■ ; 


To block 



Unused 

Resource bit 
Purge bit 
Lock bit 


Figure 12. Structure of a Master Pointer 


RESULT CODES 


Like most other Operating System routines. Memory Manager routines 
generally return a result code in addition to their normal results. 
This is an integer code indicating whether the routine completed its 
task successfully or was prevented by some error condition. The type 
definition for result codes is 


TYPE MemErr - INTEGER; 


In the normal case that no error is detected, the result code is 0; a 
nonzero result code signals an error: 


CONST noErr 

memFullErr 

nilHandleErr 

memWZErr 

memPurErr 


0; 

{no error} 

-108; 

{not enough 

-109; 

{NIL master 

-111; 

{attempt to 

-112; 

{attempt to 


room in zone} 
pointer} 

operate on a free block} 
purge a locked block} 
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To inspect a result code from Pascal, call the Memory Manager function 
MemError. This function always returns the result code from the last 
Memory Manager call. 


As s embly-language note : When called from assembly language via 
the trap mechanism, not all Memory Manager routines return a 
result code. Those that do always leave it as a word-length 
quantity in the low-order half of register D0 on return from the 
trap. However, some routines leave something else there 
instead: see the descriptions of individual routines for 
details. Just before returning, the trap dispatcher tests the 
lower half of D0 with a TST.W instruction, so that on return 
from the trap the condition codes reflect the status of the 
result code, if any. 

The stack-based Interface routines called from Pascal always 
produce a result code. If the underlying trap doesn't return 
one, the interface routine "manufactures" a result code of noErr 
and stores it where it can later be accessed with MemError. 


The ROM-based version of the Memory Manager does only limited error 
checking. This manual describes only the result codes reported by the 
ROM version. *** There may eventually be a special RAM-based version 
that will do more extensive error checking. If so, any additional 
result codes reported by the RAM version will be documented at that 
time. *** 


USING THE MEMORY MANAGER 


This section discusses how the Memory Manager routines fit into the 
general flow of your program and gives you an idea of which routines 
you'll need to use. The routines themselves are described in detail in 
the next section. 


Assembly— language note : If you're writing code that will be 
executed via a hardware interrupt, you can't use the Memory 
Manager. This is because an interrupt can occur unpredictably 
at any time. In particular, it can occur while the Memory 
Manager is in the middle of a heap compaction or in some other 
inconsistent internal state. To prevent catastrophes, interrupt 
routines are not allowed to allocate space from the heap. 


There's ordinarily no need to initialize the Memory Manager before 
using it. The system heap zone is automatically initialized each time 
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Che system is started up, and the application heap zone each time an 
application program is launched* In the unlikely event that you need 
to reinitialize the application zone while your program is running, you 
can use InitApplZone* 

You can create additional heap zones for your program’s own use, either 
from within the original application zone or from the stack, with 
InitZone. If you do maintain more than one heap zone, you can find out 
which zone is current at any given time with GetZone and switch from 
one to another with Set Zone* Almost all Memory Manager operations 
implicitly apply to the current heap zone* To refer to the system heap 
zone or the (original) application heap zone, use the Memory Manager 
function SystemZone or ApplicZone. To find out which zone a particular 
block resides in, use HandleZone (if the block is relocatable) or 
PtrZone (if it's nonrelocatable). 

(hand) 

Most applications will just use the original application 
heap zone and never have to worry about which zone is 
current* 

The main work of the Memory Manager is allocating and releasing blocks 
of memory. To allocate a new relocatable block, use NewHandle; for a 
nonrelocatable block, use NewPtr* These functions return a handle or a 
pointer, as the case may be, to the newly allocated block* You then 
use that handle or pointer whenever you need to refer to the block* 

To release a block when you're finished with it, use DisposHandle or 
DisposPtr* You can also change the size of an already allocated block 
with SetHandleSize or SetPtrSize, and find out its current size with 
GetHandleSize or GetPtrSize* Use HLock and HUnlock to lock and unlock 
relocatable blocks* 

( hand ) 

In general, you should use relocatable blocks whenever 
possible, to avoid unnecessary fragmentation of free 
space. Use nonrelocatable blocks only for things like 
I/O buffers, queues, and other objects that must have a 
fixed location in memory* For most applications, the 
only Memory Manager routines you'll ever need will be 
NewHandle, DisposHandle, and SetHandleSize* 

(hand) 

If you must lock a relocatable block, try to unlock it 
again at the earliest possible opportunity* Before 
allocating a block that you know will be locked for long 
periods of time, call ReservMem to make room for the 
block as near as possible to the beginning of the zone* 

To speed up your program, you may sometimes want to convert the handle 
to a relocatable block into a copy of the master pointer it points to* 
This is called dereferencing the handle, and allows you to refer to the 
block by single instead of double indirection* Dereferencing a handle 
can be dangerous if you aren't careful; see "Special Techniques" for 
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further information. If you ever need to convert a dereferenced master 
pointer back into the original handle, use RecoverHandle. 

Ordinarily, you shouldn't have to worry about compacting the heap or 
purging blocks from it; the Memory Manager automatically takes care of 
these chores for you. You can control which blocks are purgeable with 
HPurge and HNoPurge. If for some reason you want to compact or purge 
the heap explicitly, you can do so with CompactMem or PurgeMem. To 
explicitly purge a specific block, use EmptyHandle. 

(eye) 

If you're working with purgeable blocks, be careful! 

Such blocks may be removed from the heap zone at any time 
in order to satisfy a memory allocation request. So 
before attempting to access any purgeable block, always 
check its handle to make sure the block is still 
allocated. If the handle is empty (that is, if h~ * NIL, 
where h is the handle), then the block has been purged: 
before accessing it, you have to reallocate it and update 
its master pointer by calling ReallocHandle. (If it's a 
resource block, use the Resource Manager procedure 
LoadResource instead.) 

You can find out how much free space is left in a heap zone by calling 
FreeMem (to get the total number of free bytes) or MaxMem (to get the 
size of the largest single free block and the maximum amount by which 
the zone can grow). Beware, however: MaxMem also compacts and purges 
the entire zone before returning this information. To limit the growth 
of the application zone, use SetApplLimit ; to install a grow zone 
function to help the Memory Manager allocate space in a zone, use 
SetGrowZone. 


After calling any Memory Manager routine, you can examine its result 
code with MemError. 


MEMORY MANAGER ROUTINES 

This section describes all the Memory Manager procedures and functions. 
Each routine is presented first in its Pascal form (if there is one). 
For most routines, this is followed by a box containing information 
needed to use the routine from assembly language. Most Pascal 
programmers can just skip this box, although the list of result codes 
may be of interest to some. For general information on using the 
Memory Manager from assembly language, see "Using the Operating System 
from Assembly Language" *** (to be written) *** and also "Notes for 
Assembly “Language Programmers" in this manual. 
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Initialization and Allocation 


PROCEDURE Init ApplZone ; 


Trap macro 
On exit 
Result codes 


_In it ApplZone 

D0: result code (integer) 

0 $0000 noErr No error 


InitApplZone initializes the application heap zone and makes it the 
current zone* The contents of any previous application zone are 
completely wiped out; all previously existing blocks in that zone are 
discarded. InitApplZone is called by the Segment Loader when launching 
an application program; you shouldn't normally need to call it from 
within your own program. 

(eye) 

Reinitializing the application zone from within a running 
program is tricky, since the program's code itself 
resides in the application zone. To do it safely, you 
have to move the code of the running program into the 
system heap zone, jump to it there, reinitialize the 
application zone, move the code back into the application 
zone, and jump to it again. Don't attempt this operation 
unless you're sure you know what you're doing. 

The application zone has a standard initial size of 6K bytes, 
immediately following the end of the system heap zone, and can be 
expanded as needed in IK increments. Space is initially allocated for 
64 master pointers; should more be needed later, they will be added 64 
at a time. The zone's grow zone function is set to NIL. After a call 
to InitApplZone, MemError will always return noErr. 
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PROCEDURE SetApplBase (startPtr: Ptr); 


Trap macro 

_SetApplBase 

On entry 

A0: 

startPtr (pointer) 

On exit 

D0 : 

result code (integer) 

Result codes 

0 

$0000 noErr No error 


SetApplBase changes the starting address of the application heap zone 
to the address designated by startPtr, reinitializes the zone, and 
makes it the current zone. The contents of any previous application 
zone are completely wiped out; all previously existing blocks in that 
zone are discarded. SetApplBase is normally called only by the system 
itself ; you should never need to call this procedure from within your 
own program. 

Since the application heap zone begins immediately following the end of 
the system zone, changing its starting address has the effect of 
changing the size of the system zone. The system zone can be made 
larger, but never smaller; if startPtr points to an address lower than 
the current end of the system zone, it's ignored and the application 
zone's starting address is left unchanged. 

In any case, SetApplBase reinitializes the application zone to its 
standard initial size of 6K bytes, which can later be expanded as 
needed in IK increments. Space is initially allocated for 64 master 
pointers; should more be needed later, they will be added 64 at a time. 
The zone's grow zone function is set to NIL. After a call to 
SetApplBase, MemError will always return noErr. 

(eye) 

Like Ini tAppl Zone, SetApplBase is a tricky operation, 
because the code of the program itself resides in the 
application heap zone. The recommended procedure for 
doing it safely is the same as for InitApplZone (see 
above); again, don't attempt it unless you know what 
you're doing. 
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PROCEDURE InitZone (growProc: ProcPtr; masterCount: INTEGER; limitPtr, 
startPtr: Ptr); 


Trap macro InitZone 

On entry A0: pointer to parameter block 


startPtr 

(4-byte pointer) 

limitPtr 

(4-byte pointer) 

masterCount 

(2-byte integer) 

growProc 

(4-byte pointer) 


On exit D0: result code (integer) 

Result codes 0 $0000 noErr No error 


InitZone creates a new heap zone, initializes its header and trailer, 
and makes it the current zone. The startPtr parameter is a pointer to 
the first byte of the new zone; limitPtr points to the byte 
following the end of the zone. That is, the new zone will occupy 
memory addresses from ORD( startPtr) to ORD( limitPtr) — 1. 

MasterCount tells how many master pointers should be allocated at a 
time for the new zone. The specified number of master pointers are 
created initially; should more be needed later, they will be added in 
increments of this same number. For the system heap zone, masterCount 
is 32; for the application heap zone, it's 64. 

The growProc parameter is a pointer to the grow zone function for the 
new zone, if any. If you're not defining a grow zone function for this 
one, supply a NIL value for growProc. 

The new zone includes a 52-byte header and a 12-byte trailer, so its 
actual usable space runs from ORD(startPtr) + 52 through ORD(limitPtr) 

- 13. In addition, each master pointer occupies 4 bytes within this 
usable area. Thus the total available space in the zone, in bytes, is 
initially 

ORD(limitPtr) - ORD(startPtr) - 64 - 4*masterCount 

This number must not be less than 0. Note that the amount of available 
space in the zone may decrease as more master pointers are allocated. 
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After a call to InitZone, MemError will always return noErr. 


PROCEDURE SetApplLimit (zoneLimit: Ptr); 


Trap macro 

^SetApplLimit 

On entry 

A0: 

zoneLimit (pointer) 

On exit 

D0: 

result code (integer) 

Result codes 

0 

$0000 noErr No error 


SetApplLimit sets the application heap limit, beyond which the 
application heap zone can't be expanded. The actual expansion isn't 
under your program's control, but is done automatically by the Memory 
Manager when necessary in order to satisfy an allocation request. Only 
the original application zone can be expanded. 

ZoneLimit is a limit pointer to a byte in memory beyond which the zone 
will not be allowed to grow. That is, the zone can grow to include the 
byte preceding zoneLimit in memory, but no farther. If the zone 
already extends beyond the specified limit it won't be cut back, but it 
will be prevented from growing any more. 

(eye) 

Notice that zoneLimit is not a byte count. To limit the 
application zone to a particular size (say 8K bytes), you 
have to write something like 

SetApplLimit(POINTER(ORD(ApplicZone) + 8192)) 

After a call to SetApplLimit, MemError will always return noErr. 
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Heap Zone Access 


FUNCTION GetZone : THz; 


_GetZone 

A0: function result (pointer) 

0: result code (Integer) 

0 $0000 no Err No error 

GetZone returns a pointer to the current heap zone* After the call, 
MemError will always return noErr. 

PROCEDURE SetZone (hz: THz); 


Trap macro 

_SetZone 

On entry 

A0 : 

hz (pointer) 

On exit 

D0: 

result code (integer) 

Result codes 

0 

$0000 noErr 


SetZone sets the current heap zone to the zone pointed to by hz. After 
the call, MemError will always return noErr. 

FUNCTION SystemZone : THz; [Pascal only] 


Trap macro 

None 


Result codes 

0 $0000 noErr 

No error 


SystemZone returns a pointer to the system heap zone. After the call, 
MemError will always return noErr. 


Assembly-language note : SystemZone is part of the Pascal 
interface to the Memory Manager, not part of the Memory Manager 


Trap macro 
On exit 

Result codes 
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itself. It doesn’t reside in ROM and can’t be called via a 
trap. To get a pointer to the system heap zone from assembly 
language, use the global variable sysZone. 


FUNCTION ApplicZone 

: THz ; 

[Pascal only] 


Trap macro 

None 



Result codes 

0 

$0000 noErr 

No error 


ApplicZone returns a pointer to the original application heap zone. 
After the call, MemError will always return noErr. 


Assembly-language note : ApplicZone is part of the Pascal 
interface to the Memory Manager, not part of the Memory Manager 
itself. It doesn’t reside in ROM and can’t be called via a 
trap. To get a pointer to the application heap zone from 
assembly language, use the global variable applZone. 


Allocating and Releasing Relocatable Blocks 


FUNCTION NewHandle (logicalSize : Size) : Handle; 


Trap macro 

^NewHandle 

On entry 

D0: 

logicalSize (long integer) 

On exit 

A0 : 

function result (handle) 


0: 

result code (integer) 

Result codes 

0 

-108 

$0000 noErr No error 

$FF94 memFullErr Not enough room in zone 


NewHandle allocates a new relocatable block from the current heap zone 
and returns a handle to it (or NIL if a block of that size can’t be 
created). The new block will have a logical size of logicalSize bytes 
and will initially be marked unlocked and unpurgeable. 
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NewHandle will pursue all avenues open to it in order to create a 
block of the requested size, Including compacting the heap zone, 
increasing its size, purging blocks from it, and calling its grow zono 
function, if any. If all such attempts fail, or if the zone has run 
out of free master pointers and there's no room to allocate more, 
NewHandle returns NIL and MemError will return meraFullErr after the 
call* If a new block was successfully allocated, NewHandle returns a 
handle to the new block and MemError will return noErr* 


PROCEDURE DisposHandle (hs Handle); 


Trap macro 

^DisposHandle 


On entry 

A0 : 

h (handle) 


On exit 

A0: 

D0: 

0 

result code (integer) 

Result codes 

0 

-111 

$0000 noErr 
$FF91 memWZErr 

No error 

Attempt to operate 
on a free block 


DisposHandle releases the space occupied by the relocatable block whose 
handle Is h« If the block is already free, MemError will return 
memWZErr after the call; otherwise it will return noErr. 

(eye) 

After a call to DisposHandle, all handles to the released 
block become invalid and should not be used again. 




FUNCTION GetHandleSize (h: Handle) : Size; 


Trap macro 

^GetHandleSize 


On entry 

A0: 

h (handle) 


On exit 

D0 : 

if >~ 0, function result (long integer) 
if < 0, result code (integer) 

Result codes 

0 

-109 

-111 

$0000 noErr 
$FF93 nilHandleErr 
$FF9l memWZErr 

No error [Pascal only] 
NIL master pointer 
Attempt to operate 


on a free block 




GetHandleSize returns the logical size, in bytes, of the relocatable 
block whose handle is h. After the call, MemError will return 
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nilHandleErr if h points to a NIL master pointer, memWZErr if h is the 
handle of a free block, and noErr otherwise. In case of an error, 
GetHandleSize returns a result of 0. 


Assembly-language note : Recall that the trap dispatcher sets 
the condition codes before returning from a trap by testing the 
low-order half of register D0 with a TST.W instruction. Since 
the block size returned in D0 by _GetHandleSize is a full 32-bit 
long word, the word-length test sets the condition codes 
incorrectly in this case. To branch on the contents of D0, use 
your own TST.L instruction on return from the trap to test the 
full 32 bits of the register. 


PROCEDURE SetHandleSize (h: Handle; newSize: Size); 


Trap macro 

_SetHandleSize 


On entry 

A0 : 

h (handle) 



D0: 

newSize (long integer) 


On exit 

D0 : 

result 

code (integer) 


Result codes 

0 

$0000 

noErr No error 



-108 

$FF94 

memFullErr Not enough 

room to grow 


-109 

$FF93 

nilHandleErr NIL master 

pointer 


-111 

$FF91 

memWZErr Attempt to 

operate 




on a free 1 

block 


SetHandleSize changes the logical size of the relocatable block whose 
handle is h to newSize bytes. After the call, MemError will return 
memFullErr if newSize is greater than the block's current size and 
enough room can't be found for the block to grow, nilHandleErr if h 
points to a NIL master pointer, memWZErr if h is the handle of a free 
block, and noErr otherwise. 
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FUNCTION HandleZone (h: Handle) : THz ; 


Trap macro 

^HandleZone 


On entry 

A0 : 

h (handle) 


On exit 

A0 : 
D0 : 

function result (pointer) 
result code (integer) 

Result codes 

0 

-111 

$0000 noErr 
$FF91 memWZErr 

No error 

Attempt to operate 
on a free block 


HandleZone returns a pointer to the heap zone containing the 
relocatable block whose handle is h. 

If handle h is empty (points to a NIL master pointer), HandleZone 
returns a pointer to the current heap zone and doesn’t report an error: 
after the call, MemError will return noErr. If h is the handle of a 
free block, MemError will return memWZErr; in this case, the result 
returned by HandleZone is meaningless and should be ignored. 


FUNCTION RecoverHandle (p: Ptr) : Handle; 


Trap macro 

^Recover Handle 


On entry 

A0: 

p (pointer) 


On exit 

A0s 
D0 : 

function result 
unchanged ( ! ) 

(handle) 

Result codes 

0 

$0000 noErr 

No error [Pascal only] 


RecoverHandle returns a handle to the relocatable block pointed to by 
p. If you've "dereferenced" a handle (converted it to a simple 
pointer) for efficiency, you can use this function to get back the 
original handle. After the call, MemError will always return noErr. 


Assembly-language note : Through a minor oversight, the trap 
^Recover Handle neglects to return a result code in register D0; 
the previous contents of D0 are preserved unchanged. The stack- 
based interface routine called from Pascal always produces a 
result code of noErr. 
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PROCEDURE ReallocHandle (h: Handle; logicalSize: Size); 


Trap macro 

^ReallocHandle 


On entry 

A0: 

h (handle) 



D0: 

logicalSize (long integer) 

On exit 

A0: 

original h or NIL 



D0 : 

result 

code (integer) 

Result codes 

0 

$0000 

noErr 

No error 


-108 

$FF94 

memFullErr 

Not enough room in zone 


-111 

$FF91 

memWZErr 

Attempt to operate 





on a free block 


-112 

$FF90 

memPurErr 

Block is locked 


ReallocHandle allocates a new relocatable block with a logical size of 
logicalSize bytes. It then updates handle h by setting its master 
pointer to point to the new block. The main use of this procedure is 
to reallocate space for a block that has been purged. Normally h is an 
empty handle , but it need not be: if it points to an existing block, 
that block is released before the new block is created. 

After the call, MemError will return noErr if ReallocHandle succeeds in 
allocating a block of the requested size; if room can't be made for the 
requested block, it will return memFullErr. If h is the handle of an 
existing block, MemError will return memPurErr if the block is locked 
and memWZErr if it's already free. In case of an error, no new block 
is allocated and handle h is left unchanged. 


Assembly-language note : On return from ^ReallocHandle , register 
A0 contains the original handle h, or 0 (NIL) if no room could 
be found for the requested block. 
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Allocating and Releasing Nonrelocatable Blocks 


FUNCTION NewPtr (logicalSize : Size) : Ptr; 



Trap macro 

_NewPtr 


On entry 

D0: 

logicalSize (long integer) 


On exit 

A0: 
D0 : 

function result (pointer) 
result code (integer) 


Result codes 

0 

-108 

§0000 noErr No error 

$FF94 memFullErr Not enough room in zone 


NewPtr allocates a new nonrelocatable block from the current heap 
zone and returns a pointer to it (or NIL if a block of that size can't 
be created ). The new block will have a- logical size of logicalSize 
bytes. 

NewPtr will pursue all avenues open to it in order to create a free 
block of the requested size, including compacting the heap zone, 
increasing its size, purging blocks from it, and calling its grow zone 
function, if any. If all such attempts fail, NewPtr returns NIL and 
MemError will return memFullErr after the call. If a new block was 
successfully allocated, NewPtr returns a pointer to the new block and 
MemError will return noErr. 




PROCEDURE DisposPtr (p: Ptr); 


Trap macro 

_DisposPtr 


On entry 

A0: 

p (pointer) 


On exit 

A0: 

D0: 

0 

result code (integer) 

Result codes 

0 

-111 

§0000 noErr 
§FF91 memWZErr 

No error 

Attempt to operate 
on a free block 


DisposPtr releases the space occupied by the nonrelocatable block 
pointed to by p. If the block Is already free, MemError will return 
raemWZErr after the call; otherwise it will return noErr. 


/^S 
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(eye) 

After a call to DisposPtr, all pointers to the released 
block become invalid and should not be used again. 


FUNCTION GetPtrSize (p: Ptr) : Size; 


Trap macro 

_GetPtrSize 


On entry 

A0: 

p (pointer) 


On exit 

D0 : 

if >“ 0, function result (long integer) 
if < 0, result code (integer) 

Result codes 

0 

-111 

$0000 noErr 
$FF91 memWZErr 

No error [Pascal only] 
Attempt to operate 


on a free block 


GetPtrSize returns the logical size, in bytes, of the nonrelocatable 
block pointed to by p. After the call, MlemError will return memWZErr 
if p points to a free block and noErr otherwise. In case of an error, 
GetPtrSize returns a result of 0. 


Assembly-language note ; Recall that the trap dispatcher sets 
the condition codes before returning from a trap by testing the 
low-order half of register D0 with a TST.W instruction. Since 
the block size returned in D0 by _GetPtrSize is a full 32-bit 
long word, the word-length test sets the condition codes 
incorrectly in this case. To branch on the contents of D0, use 
your own TST.L instruction on return from the trap to test the 
full 32 bits of the register. 
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PROCEDURE SetPtrSize (p: Ptr; newSlze: Size); 


Trap macro 

_SetPtrSize 


On entry 

A0 : 

p (pointer) 



D0 : 

newSize (long integer) 


On exit 

D0: 

result code (integer) 


Result codes 

0 

$0000 noErr No error 



-108 

$FF94 memFullErr Not enough 

room to grow 


-111 

$FF91 memWZErr Attempt to 

operate 



on a free 1 

block 


SetPtrSize changes the logical size of the nonrelocatable block pointed 
to by p to newSize bytes. After the call, MemError will return 
memFullErr if newSize is greater than the block's current size and 
enough room can't be found for the block to grow, memWZErr if p points 
to a free block, and noErr otherwise. 


FUNCTION PtrZone (p: Ptr) : THz ; 


Trap macro 

_PtrZone 


On entry 

A0: 

p (pointer) 


On exit 

A0: 

function result 

(pointer) 


D0 : 

result code (integer) 

Result codes 

0 

$0000 noErr 

No error 


-111 

$FF91 memWZErr 

Attempt to operate 
on a free block 


PtrZone returns a pointer to the heap zone containing the 
nonrelocatable block pointed to by p. If p points to a free block, 
MemError will return memWZErr after the call; in this case, the result 
returned by PtrZone is meaningless and should be ignored. 
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Freeing Space on the Heap 


FUNCTION FreeMem : Longlnt; 


Trap macro 
On exit 
Result codes 


_FreeMem 

D0: function result (long integer) 

0 $0000 noErr No error [Pascal only] 


FreeMem returns the total amount of free space in the current heap 
zone, in bytes. Notice that it may not actually be possible to 
allocate a block of this size, because of fragmentation due to 
nonrelocatable or locked blocks. After a call to FreeMem, MemError 
will always return noErr. 


FUNCTION MaxMera (VAR grow: Size) : Size; 


Trap macro _MaxMera 


On exit 


D0: function result (long integer) 
A0: grow (long integer) 


Result codes 


0 $0000 noErr 


No error [Pascal only] 


MaxMem compacts the current heap zone and purges all purgeable blocks 
from the zone. It returns as its result the size in bytes of the 
largest contiguous free block in the zone after the compaction. If the 
current zone is the original application heap zone, the variable 
parameter grow is set to the maximum number of bytes by which the zone 
can grow. For any other heap zone, grow is set to 0. MaxMem doesn t 
actually expand the zone or call its grow zone function. After the 
call, MemError will always return noErr. 
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FUNCTION CompactMem (cbNeeded: Size) : Size; 


Trap macro 

jCompactMem 

On entry 

D0 : 

cbNeeded (long integer) 

On exit 

D0: 

function result (long integer) 


A0 : 

pointer to desired block or NIL 

Result codes 

0 

$0000 noErr No error [Pascal only] 


CompactMem compacts the current heap zone by moving relocatable blocks 
forward and collecting free space together until a contiguous block of 
at least cbNeeded free bytes is found or the entire zone is compacted « 
For each block that’s moved, the master pointer is updated so that all 
handles to the block remain valid* CompactMem returns the size in 
bytes of the largest contiguous free block it finds, but doesn’t 
actually allocate the block* After the call, MemError will always 
return noErr* 

( hand ) 

To force a compaction of the entire heap zone, set 

cbNeeded equal to maxSize* 


Assembly-language note ; On return from ^CompactMem, register A0 
contains a pointer to a free block of at least cbNeeded bytes, 
or 0 (NIL) if no such block could be found* 




FUNCTION ResrvMem (cbNeeded: Size); 


Trap macro 

_ResrvMem 


On entry 

D0 : 

cbNeeded (long integer) 


On exit 

A0: 

D0; 

pointer to desired block 
result code (integer) 

or NIL 

Result codes 

0 

-108 

$0000 noErr No error 

$FF94 memFullErr Not enough 


ResrvMem creates free space for a block of cbNeeded contiguous bytes at 
the lowest possible position in the current heap zone* It will try 
every available means to place the block as close as possible to the 
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beginning of the zone, including moving other blocks upward, expanding 
the zone, or purging blocks from it. If a free block of at least the 
requested size can't be created, MemError will return memFullErr after 
the call; otherwise it will return noErr. Notice that ResrvMem doesn't 
actually allocate the block. 

(hand) 

When you allocate a relocatable block that you know will 
be locked for long periods of time, call ResrvMem first. 

This reserves space for the block near the beginning of 
the heap zone, where it will interfere with compaction as 
little as possible. It isn't necessary to call ResrvMem 
for a nonrelocatable block; NewPtr calls it 
automatically. 


Assembly-language note : On return from ^ResrvMem, register A0 
contains a pointer to the desired free block of at least 
cbNeeded bytes, or 0 (NIL) if no such block could be created. 


FUNCTION PurgeMem (cbNeeded: Size); 


Trap macro 

^PurgeMem 

On entry 

D0 : 

cbNeeded (long integer) 

On exit 

A0: 

D0: 

pointer to desired block or NIL 
result code (integer) 

Result codes 

0 

-108 

$0000 noErr No error 

$FF94 memFullErr Not enough room in zone 


PurgeMem purges blocks from the current heap zone until a contiguous 
block of at least cbNeeded free bytes is created or the entire zone is 
purged. Only relocatable, unlocked, purgeable blocks can be purged. 

If a free block of at least the requested size is found, MemError will 
return noErr after the call; if not, it will return memFullErr. Notice 
that PurgeMem doesn't actually allocate the block. 

(hand) 

To force a purge of the entire heap zone, set cbNeeded 
equal to maxSize. 
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Assembly-language note : On return, from ^JPurgeMem* register A# 
contains a pointer to a free block of at least cbNeeded bytes, 
or 0 (NIL) if no such block could be found* 


PROCEDURE EmptyHandle (h: Handle); 


Trap macro 

__Empty Handle 



On entry 

A0: 

h (handle) 



On exit 

A0: 

D0: 

h (handle) 

result code (integer) 


Result codes 

0 

-111 

-112 

$0000 

$FF91 

$FF90 

noErr 

memWZErr 

memPurErr 

No error 

Attempt to operate 
on a free block 
Block is locked 


EmptyHandle empties handle h: that is, it purges the relocatable block 
whose handle is h from its heap zone and sets its master pointer to 
NIL* If h is already empty, EmptyHandle does nothing. 

(hand) 

The main use of this procedure is to release the space a 
block occupies without having to update every existing 
handle to the block* Since the space occupied by the 
master pointer itself remains allocated, all handles 
pointing to it remain valid but become empty* When you 
later reallocate space for the block with ReallocHandle , 
the master pointer will be updated, causing all existing 
handles to point correctly to the new block* 

The block whose handle is h must be unlocked, but need not be 
purgeable: if you ask to purge an unpurgeable block, EmptyHandle 
assumes you know what you're doing and purges the block as requested* 

If the block is locked, EmptyHandle doesn't purge it; after the call, 
MemError will return memPurErr* If the block is already free, MemError 
will return memWZErr. 
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Properties of Relocatable Blocks 


PROCEDURE HLock (h: Handle); 


Trap macro 

_HLock 



On entry 

A0: 

h (handle) 


On exit 

D0 : 

result 

code (integer) 


Result codes 

0 

-109 

-111 

$0000 

$FF93 

$FF91 

noErr No error 

nilHandleErr NIL master 
memWZErr Attempt to 

on a free 

pointer 

operate 

block 


HLock locks a relocatable block, preventing it from being moved within 
its heap zone* After the call, MemError will return nilHandleErr if 
handle h is empty or raemWZErr if it points to a free block, otherwise 
noErr. If the block is already locked, HLock does nothing. 


PROCEDURE HUnlock (h: Handle); 


Trap macro 

JiUnlock 




On entry 

A0 : 

h (handle) 



On exit 

D0 : 

result 

code (integer) 



Result codes 

0 

-109 

-111 

$0000 

$FF93 

$FF9l 

noErr 

nilHandleErr 

memWZErr 

No error 
NIL master 
Attempt to 
on a free 

pointer 

operate 

block 


HUnlock unlocks a relocatable block, allowing it to be moved within its 
heap zone. After the call, MemError will return nilHandleErr if handle 
h is empty or raemWZErr if it points to a free block, otherwise noErr. 

If the block is already unlocked, HUnlock does nothing. 


10/10/83 Chernicoff 


CONFIDENTIAL 


/ MEM . MGR/ MEMORY . 5 


MEMORY MANAGER ROUTINES 


43 


PROCEDURE H Purge (h: Handle); 


Trap macro 

_HPurge 




On entry 

A0: 

h (handle) 



On exit 

D0: 

result 

code (integer) 


Result codes 

0 

$0000 

noErr 

No error 



-109 

$FF93 

nilHandleErr 

NIL master 

pointer 


-111 

$FF91 

memWZErr 

Attempt to 

operate 





on a free 

block 


HPurge marks a relocatable block as purgeable. After the call, 
MemError will return nilHandleErr if handle h is empty or memWZErr if 
it points to a free block, otherwise noErr. If the block is already 
purgeable, HPurge does nothing. 


PROCEDURE HNo Purge (hr Handle); 


Trap macro 

_HNo Purge 




On entry 

A0: 

h (handle) 



On exit 

D0 : 

result 

code (integer) 


Result codes 

0 

-109 

-111 

$0000 

$FF93 

$FF91 

noErr 

nilHandleErr 

memWZErr 

No error 
NIL master 
Attempt to 
on a free 

pointer 

operate 

block 


HNoPurge marks a relocatable block as unpurgeable. After the call, 
MemError will return nilHandleErr if handle h is empty or memWZErr if 
it points to a free block, otherwise noErr. If the block is already 
unpurgeable, HNoPurge does nothing. 
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Grow Zone Functions 


PROCEDURE SetGrowZone (growZone: ProcPtr); 


Trap macro 

^SetGrowZone 

On entry 

A0: 

growZone (pointer) 

On exit 

D0: 

result code (integer) 

Result codes 

0 

$0000 noErr 


SetGrowZone sets the current heap zone's grow zone function as 
designated by the growZone parameter* A NIL parameter value removes 
any grow zone function the zone may previously have had* After the 
call, MemError will always return noErr* 

(hand) 

If your program presses the limits of the available heap 
space, it's a good idea to have a grow zone function of 
some sort* At the very least, the grow zone function 
should detect when the Memory Manager is about to run out 
of space at a critical time (see GZCritical, below) and 
take some graceful action — such as displaying an alert 
box with the message "Out of memory" — instead of just 
failing unpredictably* *** There may eventually be a 
default grow zone function that does this* *** 

The Memory Manager calls the grow zone function as a last resort when 
trying to allocate space, after failing to create a block of the needed 
size by compacting the zone, increasing its size (in the case of the 
original application zone), or purging blocks from it* Memory Manager 
routines that may cause the grow zone function to be called are 
NewHandle, NewPtr, SetHandleSize , SetPtrSize, ReallocHandle , and 
ResrvMem* 

The grow zone function should be of the form 

FUNCTION GrowTheZone (cbNeeded: Size) : Size; 

(Of course, the name GrowTheZone is only an example; you can give the 
function any name you like*) The cbNeeded parameter gives the physical 
size of the needed block in bytes, including the block header* The 
grow zone function should attempt to create a free block of at least 
this size. It should return as its result the number of additional 
bytes it has freed within the zone, but this number need not be 
accurate* 
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If the grow zone function returns 0„ the Memory Manager will give uo 
trying to allocate the needed block and will signal failure with the 
result code. memFullErr. Otherwise it will compact the heap zone and 
try again to allocate the block. If still unsuccessful, it will 
continue to call the grow zone function repeatedly, compacting the zone 
again after each call, until it either succeeds in allocating the 
needed block or receives a zero result and gives up. 

The usual way for the grow zone function to free more space is to call 
EmptyHandle to purge blocks that were previously marked unpurgeable. 
Another possibility is to unlock blocks that were previously locked. In 
order to eliminate immovable "islands" that may have been interfering 
with the compaction process and fragmenting the existing free space. 

(hand) 

Although just unlocking blocks doesn't actually free any 
additional space in the zone, the grow zone function 
^ should still return a nonzero result in this case. This 

signals the Memory Manager to compact the heap and try 
again to allocate the needed block. 

(eye) 

Depending on the circumstances in which the grow zone 
function is called, there may be particular blocks within 
the heap zone that must not be purged or released. For 
instance, if your program is attempting to increase the 
size of a relocatable block with SetHandleSize , it would 
be disastrous to release the block being expanded. To 
deal with such cases safely, it's essential to understand 
the use of the functions GZCritical and GZSaveHnd (see 
below). 


FUNCTION GZCritical : BOOLEAN; [Pascal only] 




Trap macro None 
Result codes None 


GZCritical returns TRUE if the Memory Manager critically needs the 
requested space: for example, to create a new relocatable or 
nonrelocatable block or to reallocate a handle. It returns FALSE in 
less critical cases, such as ResrvMem trying to move a block in order 
to reserve space as low as possible in the heap zone or SetHandleSize 
trying to increase the size of a relocatable block by moving the block 
above it. 

(eye) 

If you're writing a grow zone function in Pascal, you 
should always call GZCritical and proceed only if the 
result is TRUE. All the information you need to handle 
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the critical cases safely is the value of GZSaveHnd (see 
below). The noncritical cases require additional 
information that isn't available from Pascal, so your 
grow zone function should just return 0 and not attempt 
to free any space. 


Assembly-language note : GZCritical is part of the Pascal 
interface to the Memory Manager, not part of the Memory Manager 
itself. It doesn't reside in ROM and can't be called via a 
trap. To find out whether a given grow zone call is critical, 
use the following magical Incantation: 


MOVE . L 

gzMoveHnd ,D0 

BEQ.S 

Critical 

CMP.L 

gzRootHnd ,D0 

BEQ.S 

Critical 

CLR.L 

4(SP) 

RTS 



Critical . . . 


; If noncritical, just return 0 
; Handle critical case 


To handle the critical cases safely (and the noncritical ones if 
you choose to do more than just return 0), see the note below 
under GZSaveHnd. 




FUNCTION GZSaveHnd : Handle; [Pascal only] 


Trap macro None 
Result codes None 




GZSaveHnd returns a handle to a relocatable block that mustn't be 
purged or released by the grow zone function, or NIL if there is no 
such block. The grow zone function will be safe if it avoids purging 
or releasing this block, provided that the grow zone call was 
critical. To handle noncritical cases safely, further information is 
needed that isn't available from Pascal. 


Assembly— language note : GZSaveHnd is part of the Pascal 
interface to the Memory Manager, not part of the Memory Manager 
itself. It doesn't reside in ROM and can't be called via a 
trap. You can find the handle it returns in the global variable 
gzRootHnd. The "further information" that isn't available from 
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Pascal Is the contents of two other global variables, gzRootPtr 
and gzMoveHnd, which may be nonzero in noncritical cases. If 
gzRootPtr is nonzero, it's a pointer to a nonrelocatable block 
that must not be released; gzMoveHnd is a handle to a 
relocatable block that must not be released but may be purged. 


Utility Routines 


PROCEDURE BlockMove (sourcePtr ,destPtr : Ptr; byteCount: Size); 



Trap macro 

^BlockMove 



On entry 

A0 : 
A1 : 
D0: 

sourcePtr (pointer) 
destPtr (pointer) 
byteCount (long Integer) 



On exit 

D0: 

result code (integer) 



Result codes 

0 

$0000 noErr No error 



BlockMove moves a block of byteCount consecutive bytes from the address 
designated by sourcePtr to that designated by destPtr. No checking of 
any kind is done on the addresses; no pointers are updated. After the 
call, MemError will always return noErr. 




FUNCTION TopMem : Ptr; [Pascal only] 


Trap macro None 

Result codes 0 $0000 noErr No error 

TopMem returns a pointer to the address following the last byte of 
physical memory. After the call, MemError will always return noErr. 


Assembly-language note : TopMem is part of the Pascal interface 
to the Memory Manager, not part of the Memory Manager itself. 

It doesn't reside in ROM and can't be called via a trap. To get 
a pointer to the end of physical memory from assembly language, 
use the global variable memTop. 
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FUNCTION MemError : MemErr; [Pascal only] 


Trap macro 

None 

Result codes 

None 


MemError returns the result code produced by the last Memory Manager 
routine to be called* 


As sembly~language note : MemError is part of the Pascal 
interface to the Memory Manager, not part of the Memory Manager 
itself* It doesn’t reside in ROM and can’t be called via a 
trap. To get the a routine’s result code from assembly 
language, look in register D0 on return from the routine* 


SPECIAL TECHNIQUES - 

This section describes some special or unusual techniques that you may 
find useful. 


Dereferencing a Handle — — - — 

Accessing a block by double indirection, through a handle instead of a 
simple pointer, requires an extra memory reference* For efficiency, 
you may sometimes want to dereference the handle -"—that is, convert it 
to a copy of the master pointer, then use that pointer to access the 
block by single indirection. But be careful! Any operation that 
allocates space from the heap may cause the underlying block to be 
moved or purged* In that event, the master pointer itself will be 
correctly updated, but your copy of it will be left dangling. 

One way to avoid this common type of program bug is to lock the block 
before dereferencing its handle: for example. 
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VAR aPointer: Ptr; 
aHandle: Handle; 

• ■ • ! 

BEGIN 


aHandle 


NewHandle( . 


HLock( aHandle ) ; 
aPointer := aHandle' 1 ; 


WHILE ... DO 
BEGIN 

. . •aPointer' 1 . . . 

END; 


); {create a relocatable block} 

{lock block before dereferencing} 
{convert handle to simple pointer} 


{use simple pointer inside loop} 


HUnlock( aHandle); 


{unlock block when finished} 




END 


Assembly-language note : To dereference a handle in assembly 
language, just copy the master pointer into an address register 
and use it to access the block by single indirection* Remember 
that the master pointer points to the block’s contents, not its 
header ! 

MOVE.L //blockSize ,D0 ;set up block size for _NewHandle 


NewHandle 

;create relocatable block 

MOVE • L 

A0 , aHandle 

;save handle for later use 

• • • 

MOVE . L 

aHandle , A1 

;get back handle 

MOVE.L 

A1 ,A0 

;lock block before dereferencing 

_HLock 



MOVE.L 

(A1),A2 

; convert handle to simple pointer 

LOOP . . . 



MOVE 

. « . ( A2 ) . • . 

;use simple pointer inside loop 

• • • 

Bcc • S 

LOOP 

;loop back on some condition 

MOVE.L 

A1,A0 

; unlock block when finished 

_HUnlock 



Remember, however, that when you lock a block it becomes an "island* 1 in 
the heap that may interfere with compaction and cause free space to 
become fragmented* It’s recommended that you use this technique only 
in parts of your program where efficiency is critical, such as inside 
tight inner loops that are executed many times* 


t 
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(eye) 

Don't forget to unlock the block again when you're 
through with the dereferenced handle! 

Instead of locking the block, you can update your copy of the master 
pointer after any "dangerous" operation (one that can invalidate the 
pointer by moving or purging the block it points to). Memory Manager 
routines that can move or purge blocks in the heap are NewHandle, 
NewPtr, SetHandleSize, SetPtrSize, ReallocHandle, ResrvMem, CompactMem, 
PurgeMera, and MaxMem. Since these routines can be called indirectly 
from other Operating System or Toolbox routines, you should assume that 
any call to the OS or Toolbox can potentially leave your dereferenced 
pointer dangling. *** Eventually there will be a technical note 
listing which OS and Toolbox routines are dangerous and which 
aren't. *** 

(hand) 

If you aren't performing any dangerous operations, you 
needn't worry about updating the pointer (or locking the 
block either, for that matter). 


Subdividing the Application Heap Zone 

In some applications, you may want to subdivide the original 
application heap zone into two or more independent zones to be used for 
different purposes. In doing this, it's important not to destroy any 
existing blocks in the original zone (such as those containing the code 
of your program). The recommended procedure is to allocate space for 
the subzones as nonrelocatable blocks within the original zone, then 
use InitZone to initialize them as independent zones. For example, to 
divide the available space in the application zone in half, you might 
write something like the following: 
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CONST minSize =■ 52 + 12 + 32*(12 + 4); 


VAR my Zone 1, my Zone 2: THz; 
start, limit: Ptr; 
availSpace, zoneSize: Size; 
. . . ; 

BEGIN 


{zone header, zone trailer,} 

{ and 32 minimum-size blocks} 
{ with master pointers} 


• • • * 

Set Zone ( ApplicZone) ; 

availSpace : a CompactMem(maxSize) ; 

zoneSize 2 * (availSpace DIV 4); 

IF zoneSize < (minSize + 8) 

THEN . . . 

ELSE 

BEGIN 

zoneSize :=> zoneSize - 8; 


{size of largest free block} 
{force new zone size to an} 

{ even number of bytes} 
{need 8 bytes for} 

{ block header} 

{error — not enough room} 


{adjust for block header} 


start := NewPtr( zoneSize ) ; {allocate a nonrel. block} 
limit := POINTER(ORD( start) + zoneSize); 

InitZone(NIL, 32, limit, start); 

myZonel POINTER(ORD(start)) ; {convert Ptr to THz} 


start := NewPtr(zoneSize) ; {allocate a nonrel. block} 
limit :=• POINTER(ORD( start) + zoneSize); 

InitZone(NIL, 32, limit, start); 

myZone2 :=* POINTER(ORD(start)) {convert Ptr to THz} 
END; 
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Assembly-language note t The equivalent assembly code might be 


minSize 


.EQU 


52+12+<32*<12+4» 


zone header and trailer, plus 
32 minimum-size blocks 
with master pointers 


MOVE.L applZone,A0 
Set Zone 


;get original application zone 
;make it current 


MOVE.L #maxSize,D0 ; compact entire zone 
CompactMem ;D0 has size of largest free block 


ASR.L #2 ,D0 ;force new zone size to an 

ASL.L #1,D0 ; even number of bytes 

CMP.L //minSize+8 ,D0 ;need 8 bytes for block header 

BLO NoRoom ;error if < minimum size 


SUBQ.L #8 ,D0 
MOVE.L D0,D1 
__NewPtr 

MOVE.L A0 .myZonel 


; adjust for block header 
;save zone size 

;allocate nonrelocatable block 
;store zone pointer 


CLR.L -(SP) 
MOVE.W # 32, -(SP) 
MOVE.L A0 ,-( SP) 
ADD. L D1 , (SP) 
MOVE.L A0 ,-( SP) 


;NIL grow zone function 
;allocate 32 master pointers 
;A0 has zone pointer 
; convert to limit pointer 
;push as start pointer 


MOVE.L SP, A0 ; point to argument block 

InitZone jcreate zone 1 


MOVE.L D1,D0 
_NewPtr 

MOVE.L A0,myZone2 


;get back zone size 
; allocate nonrelocatable block 
;store zone pointer 


MOVE.L A0 ,4( SP) 
ADD.L D1 , ( SP) 

MOVE.L A0 , ( SP ) 


;move zone pointer to stack 
jconvert to limit pointer 
;move to stack as start pointer 


MOVE.L SP.A0 
_InitZone 
ADD. W #14, SP 


; point to argument block 

; create zone 2 

;pop arguments off stack 
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Creating a Heap Zone on the Stack 

Another place you can get the space for a new heap zone is from the 
stack. For example, 

CONST zoneSize = 2048; 

VAR zoneArea: PACKED ARRAY [ l .. zoneSize] OF SignedByte; 
stackZone: THz; 
limit: Ptr; 

• • • 5 

BEGIN 

• • • » 

stackZone :« @zoneArea; 

limit :=■ POINTER(ORD( stackZone) + zoneSize); 

Ini t Zone (NIL, 16, limit, @zoneArea); 


END 


Assembly-language note : Here's how you might do the same thing 
in assembly language: 


zoneSize 


.EQU 

2048 


• • • 

MOVE.L 

SP,A2 

;save stack pointer for limit 

SUB.W 

#zoneSize,SP 

;make room on stack 

MOVE.L 

SP,A1 

;save stack pointer for start 

MOVE.L 

Al , stackZone 

;store as zone pointer 

CLR.L 

-(SP) 

;NIL grow zone function 

MOVE.W 

#16, -(SP) 

;allocate 16 master pointers 

MOVE.L 

A2 ,-( SP) 

;push limit pointer 

MOVE.L 

Al ,-(SP) 

;push start pointer 

MOVE.L 

SP, A0 

; point to argument block 


_InitZone ; create new zone 

ADD.W #14, SP ;pop arguments off stack 



54 Memory Manager Programmer's Guide 




notes for assembly-language programmers 

General information about how to use the Macintosh Operating System 
from assembly language is *** (will be) *** given elsewhere. This 
section contains special notes of interest to programmers who will be 
using the Memory Manager from assembly language. 

The primary aids to assembly-language programmers are files named 
SYSEQU.TEXT, SYSMACS.TEXT, SYS ERR. TEXT, and HEAPDEF S • TEXT • If you use 
.INCLUDE to include these files when you assemble your program, all the 
Memory Manager constants, addresses of global variables, trap macros, 
error codes, and masks and offsets into fields of structured types will 
be available in symbolic form. 


Constants 

The file HEAPDEFS.TEXT defines a number of useful constants that you ^ 

can use in your program as immediate data values. For example, to push 
the default master-point count onto the stack as an argument for 
_InitZone, you might write 

MOVE • W #df ltMasters ,-( SP) 


(hand) 

It's a good idea to refer to these constants in your 
program by name instead of using the numeric value 
directly, since some of the values shown may be subject 
to change. Some of the constants are based on an 
eventual 512K memory configuration; the present Macintosh 
has 128K of RAM. 


lowing constants are 

defined in 

HEAPDEFS.TEXT: 

minFree 

.EQU 

12 

;minimum block size 

maxSize 

.EQU 

$7FFFF 

;maximum block size (512K - 1) f. 

minAddr 

.EQU 

0 

;minimum legal address 

maxAddr 

.EQU 

$80000 

;maximum legal address (512K) 

df ltMasters 

.EQU 

32 

;default master-pointer count 

maxMasters 

.EQU 

$1000 

;maximum master-pointer count (4K) 

sysZoneSize 

.EQU 

$4000 

;size of system heap zone (16K) 

applZoneSize 

.EQU 

$1800 

;initial size of application zone (6K) 

minZone 

.EQU 

heapData+<4*minFree>+<8*dfltMasters> 

;minimum size of application zone 

df ltgtackSize 

.EQU 

$00002000 

; initial space allotment for stack (8K) 

tybkFree 

.EQU 

0 

;tag value for free block 

tybkNRel 

• EQU 

1 

; tag value for nonrelocatable block 

tybkRel 

.EQU 

2 

;tag value for relocatable block 







NOTES FOR ASSEMBLY-LANGUAGE PROGRAMMERS 


55 


One global constant pertinent to the Memory Manager is defined in 
SYSEQU.TEXT: 

heapStart .EQU $0B00 ;start address of 

; system heap zone (2816) 


Global Variables 


The Memory Manager's global variables are located in the system 
communication area and defined in the file SYSEQU.TEXT* To access a 
global variable, just refer to it by name as an absolute address. For 
example, to load a pointer to the current heap zone into register A2, 
write 


MOVE.L theZone ,A2 


The following global variables are used by the Memory Manager: 


Variable 

memTop 

bufPtr 

minStack 

def ItStack 

heapEnd 

applLimit 

sysZone 

applZone 

theZone 


Contents 

Limit address (end plus one) of physical memory 
Base address of stack (grows downward from here) 
Minimum space allotment for stack (IK) 

Default space allotment for stack (8K) 

Current limit address of application heap zone 

Application heap limit 

Address of system heap zone 

Address of application heap zone 

Address of current heap zone 


Trap Macros 

All assembly-language trap macros for the Memory Manager (as well as 
the rest of the Operating System) are defined in the file SYSMACS.TEXT. 
To call a Memory Manager routine from assembly language via the trap 
mechanism, just use the name of the trap macro as the operation code of 
an instruction. For example, to find out the number of free bytes in 
the current heap zone, use the instruction 

_FreeMem 

As stated in the description of FreeMem above, the ^number of free bytes 
will be in register D0 on return from the trap. 
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Result Codes 


The file SYSERR. TEXT contains constant definitions for all result codes 
returned by Operating System routines. You can use them in your 
program as immediate data values. For example, to test for the error 
code memFullErr on return from a trap, you might write 


CMP.W //memFullErr, D0 
BEQ No Room 


The Memory Manager uses the following error codes : 


noErr 

memFullErr 

nilHandleErr 

memWZErr 

raemPurErr 

Offsets and Masks 

.EQU 

.EQU 

.EQU 

.EQU 

.EQU 

0 

-108 

-109 

-111 

-112 

;no error 

;not enough room in zone 

; NIL master pointer 

;attempt to operate on a free block 

; attempt to purge a locked block 

Offsets to the fields of zone and block 

headers are defined as 

constants in the file HEAPDEFS.TEXT. 

To 

access a field, use the name 

of the offset constant as a 

displacement 

relative to an address 

register pointing to 

the first byte of the header* For example, if 

register A2 contains 

a pointer to a zone 

header, you can load the 

number of free bytes 

in the 

zone into 

D3 

with the instruction 


MOVE.L 

gzProc(A2) , 

D3 

(eye) 





Generally speaking, 

the offset 

and mask constants 

discussed here are intended for the Memory Manager s 

internal use* 

You shouldn't ordinarily be prowling 

around in a zone or 

block header 

unless you know what 

you're doing* 





The following offset 

constants represent the fields of a zone header: 

bkLim 

.EQU 

0 

] 

address of zone trailer (long) 

purgePtr 

.EQU 

4 

: 

roving purge pointer (long) 

hFstFree 

.EQU 

8 

! 

address of first free 





master pointer (long) 

zcbFree 

.EQU 

12 

: 

number of free bytes (long) 

gzProc 

.EQU 

16 


address of grow zone 





function (long) 

moreMasters 

.EQU 

20 


incremental master-pointer 





count (word) 

flags 

.EQU 

22 


internal flags (word) 

cntRel 

.EQU 

24 


relocatable blocks (word) 
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maxRel 

.EQU 

26 

;max. cntRel so far (word) 

cntNRel 

.EQU 

28 

;nonrelocatable blocks (word) 

maxNRel 

• EQU 

30 

;max. cntNRel so far (word) 

cntEmpty 

.EQU 

32 

;empty master pointers (word) 

cntHandles 

.EQU 

34 

;total master pointers (word) 

minCBFree 

.EQU 

36 

;min. zcbFree so far (long) 

purgeProc 

.EQU 

40 

;address of purge warning 
; procedure (long) 

sparePtr 

.EQU 

44 

;spare pointer (long) 

allocPtr 

.EQU 

48 

; roving allocation pointer (long) 

heapData 

.EQU 

52 

;first usable byte in zone 

The following offset 

constants represent the fields of a block header: 

tagBC 

.EQU 

0 

;tag, size correction, and 
; physical byte count (long) 

handle 

.EQU 

4 

;reloc.: relative handle (long) 
;nonreloc. : zone pointer (long) 

blkData 

.EQU 

8 

;first byte of block contents 


HEAPDEFS.TEXT also 

defines 

the following mask constants for 

manipulating the fields of 

block headers and master pointers: 

tagMask 

.EQU 

$00000000 

;tag field 

bcOf fMask 

.EQU 

$0F000000 

;size correction 




("byte count offset 11 ) 

bcMask 

.EQU 

$00FFFFFF 

physical byte count 

ptrMask 

.EQU 

$00FFFFFF 

►address part of master pointer 




or zone pointer 

handleMask 

.EQU 

$00FFFFFF 

[relative handle 

f reeTag 

.EQU 

0 

;tag for free block 

nRelTag 

.EQU 

$40000000 

;tag for nonrelocatable block 

re 1 Tag 

.EQU 

$80000000 

[tag for relocatable block 


(eye) 

Remember, the pointer or handle you get from the Memory 
Manager when you allocate a block points to the block's 
contents, not Its header. To get the address of the 
header, subtract the offset constant blkData, defined 
above. For example, if you have a handle to a block in 
register A2, the following code will set A3 to point to 
the block's header: 


MOVE.L (A2),A3 ;get pointer to block contents 

SUBQ.L //blkData, A3 ;offset back to header 
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Finally* SYSEQU.TEXT defines the following constants for the bit 
numbers of the various flag bits within the high-order byte of a master 
pointer: 


lock 

.EQU 

7 

;lock bit 

purge 

.EQU 

6 

{purge bit 

resource 

.EQU 

5 

{resource bit 

You can use these 

constants 

to access 

the flag bits directly, using the 


68000 instructions BSET, BCLR, and BTST. For instance, if you have a 
handle to a relocatable block in register A2, you can mark the block as 
purgeable with the instruction 


BSET.B //purge, (A2) 


;set purge bit in master pointer 


To branch 


on the current setting of the lock bit, 


BTST. B //lock, ( A2 ) 
BNE ItsLocked 


;test lock bit in master pointer 
: and branch on result 


Handy Tricks 

To save time in critical situations, here's a quick way to convert a 
dereferenced pointer to a relocatable block back into a handle without 
paying the overhead of a _RecoverHandle trap* Recall that the relative 
handle stored in the block's header is the offset of the block's master 
pointer relative to the start of its heap zone. So to convert a copy 
of the master pointer back into the original handle, find the relative 
handle and add it to the address of the zone. For example, if register 
A2 contains the master pointer of a block in the current heap zone, the 
following code will reconstruct the block's handle in A3: 

MOVE.L -4(A2),A3 ;relative handle is 4 bytes back 

; from start of contents 

ADD.L theZone,A3 ;use as offset from start of zone 

Conversely, given a true (absolute) handle to a relocatable block, you 
can find the zone the block belongs to by subtracting the relative 
handle from the absolute handle. If the absolute handle is in register 
A2, the following instructions will convert it into a pointer to the 
block's heap zone: 

MOVE.L (A2),A3 ;get pointer to block 

SUB.L -4(A3),A2 ;subtract relative handle 

; to get zone pointer 

For nonrelocatable blocks, the header contains a pointer directly back 
to the zone: 

MOVE.L -4(A2),A2 ;get zone pointer directly 
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SUMMARY OF THE MEMORY MANAGER 


CONST noErr = 0; 


memFullErr 

- -108 

nilHandleErr 

- -109 

memWZErr 

= -111 

memPurErr 

- -112 


{no error} 

{not enough room in zone} 

{NIL master pointer} 

{attempt to operate on a free block} 
{attempt to purge a locked block} 


maxSize = $800000; 

TYPE SignedByte » -128.. 127; 


Byte 

= 0. .255; 

Ptr 

= “SignedByte 

Handle 

** “Ptr; 

ProcPtr 

=» Ptr; 

Size 

= Long In t; 

MemErr 

» INTEGER; 

THz = 

“Zone ; 

Zone ■ 

RECORD 


bkLim: 

Ptr; 

purgePtr : 

Ptr; 

hFstFree : 

Ptr; 

zcbFree : 

Long In t 

gzProc: 

ProcPtr 

moreMast : 

INTEGER 

flags : 

INTEGER 

cntRel : 

INTEGER 

maxRel : 

INTEGER 

cntNRel : 

INTEGER 

maxNRel 2 

INTEGER 

cntEmpty 2 

INTEGER 

cntHandles 2 

INTEGER 

rainCBFree 2 

Longlnt 

purgeProc 2 

ProcPtr 

sparePtr : 

Ptr; 

allocPtr : 

Ptr; 

heapData: 

INTEGER 


END; 


Initialization and Allocation 


PROCEDURE Ini tAppl Zone ; 

PROCEDURE SetApplBase (startPtr: Ptr); 

PROCEDURE InitZone (growProc: ProcPtr; masterCount: INTEGER; 

limitPtr, startPtr: Ptr); 

PROCEDURE SetApplLimit (zoneLimit: Ptr); 
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Heap Zone Access 

FUNCTION Get Zone : THz; 

PROCEDURE SetZone (hz: THz); 

FUNCTION SystemZone : THz; [Pascal only] 
FUNCTION ApplicZone : THz; [Pascal only] 


Allocating and Releasing Relocatable Blocks 

FUNCTION NewHandle (logicalSize : Size) : Handle; 
PROCEDURE DisposHandle (h: Handle); 

FUNCTION GetHandleSize (h: Handle) : Size; 

PROCEDURE SetHandleSize (h: Handle; newSize: Size); 
FUNCTION Handle Zone (h: Handle) : THz; 

FUNCTION RecoverHandle (p: Ptr) : Handle; 

PROCEDURE ReallocHandle (h: Handle; logicalSize: Size); 


Allocating and Releasing Nonrelocatable Blocks 

FUNCTION NewPtr (logicalSize: Size) : Ptr; 

PROCEDURE DisposPtr (p: Ptr); 

FUNCTION GetPtrSize (p: Ptr) : Size; 

PROCEDURE SetPtrSize (p: Ptr; newSize: Size); 
FUNCTION Ptr Zone (p: Ptr) : THz; 


Freeing Space on the 

FUNCTION FreeMem : 
FUNCTION MaxMera 
FUNCTION CompactMem 
PROCEDURE ResrvMem 
FUNCTION PurgeMem 
PROCEDURE EmptyHandle 


Heap 

Long Int ; 

(VAR grow: Size) : Size; 
(cbNeeded: Size) : Size; 
(cbNeeded: Size); 
(cbNeeded: Size); 

(h: Handle); 


Properties of Relocatable Blocks 

PROCEDURE HLock (h: Handle); 
PROCEDURE HUnlock (h: Handle); 
PROCEDURE HPurge (h: Handle); 
PROCEDURE HNo Purge (h: Handle); 
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r*S 


Grow Zone Functions 


PROCEDURE SetGrowZone (growZone: ProcPtr); 
FUNCTION GZCritical : BOOLEAN; [Pascal only] 
FUNCTION GZSaveHnd : Handle; [Pascal only] 


Utility Routines 

PROCEDURE BlockMove (sourcePtr, destPtrs Ptr; byteCount: Size); 
FUNCTION TopMem : Ptr; [Pascal only] 

FUNCTION MemError : MemErr; [Pascal only] 








10/10/83 Chernlcoff 


CONFIDENTIAL 


/MEM. MGR/MEMORY. 7 


62 


Memory Manager Programmer’s Guide 


GLOSSARY 

allocate: To reserve a block for use. 

application heap zone: The heap zone provided by the Memory Manager 
for use by the application program. 

block: An area of contiguous memory within a heap zone. 

block contents: The area of a block available for use. 

block header: The internal "housekeeping" information maintained by 
the Memory Manager at the beginning of each block in a heap zone. 

compaction: The process of moving allocated blocks within a heap zone 

in order to collect the free space into a single block. 

current heap zone: The heap zone currently under attention, to which 
most Memory Manager operations implicitly apply. 

dereference: To convert a pointer into whatever it points to; 
specifically, to convert a handle into a copy of its corresponding 
master pointer. 

empty handle: A handle that points to a NIL master pointer, signifying 
that the underlying relocatable block has been purged. 

free block: A block containing space available for allocation. 

grow zone function: A function supplied by the application program to 
help the Memory Manager create free space within a heap zone. 

handle: A pointer to a master pointer, which designates a relocatable 

block by double indirection. 

heap zone: An area of memory in which space can be allocated and 
released on demand, using the Memory Manager. 

limit pointer: A pointer to the byte following the last byte of an 
area in memory, such as a block or a heap zone. 

lock: To temporarily prevent a relocatable block from being moved 
during heap compaction. 

lock bit: A bit in the master pointer to a relocatable block that 
indicates whether the block is currently locked. 

logical size: The number of bytes in a block’s contents; compare 
physical size . 
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master pointer: A single pointer to a relocatable block, maintained by 
the Memory Manager and updated whenever the block is moved, purged, or 
reallocated# All handles to a relocatable block refer to it by double 
indirection through the master pointer* 

nonrelocatable block: A block whose location in its heap zone is fixed 
and can't be moved during heap compaction. 

physical size: The actual number of bytes a block occupies within its 
heap zone* 

purge: To remove a relocatable block from its heap zone, leaving its 
master pointer allocated but set to NIL* 

purgeable block: A relocatable block that can be purged from its heap 
zone* 

purge bit: A bit in the master pointer to a relocatable block that 
indicates whether the block is currently purgeable* 

purge warning procedure: A procedure associated with a particular heap 
zone that is called whenever a block is purged from that zone. 

reallocate: To allocate new space in a heap zone for a purged block, 
updating its master pointer to point to its new location. 

relative handle: A handle to a relocatable block expressed as the 
offset of its master pointer within the heap zone, rather than as the 
absolute memory address of the master pointer* 

release: To destroy an allocated block, freeing the space it occupies* 

relocatable block: A block that can be moved within its heap zone 
during compaction* 

result code : An integer code produced by a Memory Manager routine to 
signal the success of an operation or the reason for its failure. 

size correction: The number of unused bytes included at the end of an 
allocated block; the difference between the block's logical and 
physical sizes, excluding the block header* 

system heap zone: The heap zone provided by the Memory Manager for use 
by the Macintosh system software* 

tag: A 2-bit code in the header of a block identifying it as 

relocatable, nonrelocatable, or free* 

unlock: To allow a relocatable block to be moved during heap 
compaction* 

unpurgeable block: A relocatable block that can't be purged from its 
heap zone. 
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zone header: The Internal "housekeeping" Information maintained by the 
Memory Manager at the beginning of each heap zone. 

zone pointer: A pointer to a zone record. 

zone record: A Pascal data structure representing the structure of a 
zone header. 

zone trailer: A minimum-size free block marking the end of a heap 
zone. 
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The Sound Driver is a set of data types and routines in the Macintosh 
Operating System for handling sound and music generation in a Macintosh 
application. This manual describes the Sound Driver in detail. 
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ABOUT THIS MANUAL 


t 


The Sound Driver is a set of data structures and routines in the 
Macintosh Operating System for handling sound and music generation in a 
Macintosh application* This manual describes the Sound Driver in 
detail* *** Eventually it will become part of a larger manual 
describing the entire Toolbox and Operating System* *** 

(note) 

This manual describes the Sound Driver in version 7 of 
the ROM* If you’re using a different version, the 
information presented here may not apply* 

Like all Operating System documentation, this manual assumes you’re 
familiar with Lisa Pascal* You should also be familiar with the 
following: 

- the basic concepts behind the Macintosh Operating System's Memory 
Manager 

- devices and device drivers, as described in the Device Manager 
Manual *** doesn't yet exist *** 

This manual is intended to serve the needs of both Pascal and 
assembly-language programmers* Information of interest to assembly 
language programmers only is isolated and labeled so that Pascal 
programmers can conveniently skip it* *** Currently a Pascal interface 
to the Sound Driver doesn’t exist *** 

The manual begins with an introduction to the Sound Driver and what you 
can do with it. It then steps back a little and looks at the 
mathematical and physical concepts that form the foundation for the 
Sound Driver: waveforms, wave frequency, wave amplitude, and wave 
periods* Once you understand these concepts, read on about how they’re 
translated into sound, music, and speech* 

Next, a section on using the Sound Driver describes how you can use 
Device Manager calls in your application to produce desired sounds* 

This includes a detailed description of the Sound Driver's control 
routine — its parameters, calling protocol, effects, and so on. 

Finally, there’s a summary of the Sound Driver data structures and 
routine calls, for quick reference, followed by a glossary of terms 
used in this manual. 


ABOUT THE SOUND DRIVER 


The Sound Driver is a standard Macintosh device driver used to 
synthesize sound waves. You can use the Sound Driver to generate sound 
characterized by any kind of waveform by using the three different 
sound synthesizers in the Sound Driver: 
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- The four-tone synthesizer is used to make simple harmonic tones, 
with up to four "voices" producing sound simult^ieously ; it 
requires about 50% of the microprocessor's attention during any 
given time interval. 

- The square -wave synthesizer is used to produce less harmonic 
sounds such as beeps, and requires about 2% of the processor's 
time. 

- The f ree-form synthesizer is used to make complex music and 
speech; it requires about 20% of the processor's time. 

Figure 1 depicts the waveform of a typical sound wave, and the terms 
used to describe it. The amplitude is the vertical distance between 
any given point on the wave and the horizontal line about which the 
amplitude oscillates; you can think of the amplitude of a wave as its 
volume level. The wavelength is the horizontal extent of one complete 
cycle of the wave. Both the amplitude and wavelength can be measured 
in any unit of distance. The period is the time elapsed during one 
complete cycle of a wave. The frequency is the reciprocal of the 
period, or the number of cycles per second (also called Hertz). The 
phase is some fraction of a wave cycle (measured from a fixed point on 
the wave ) • 



frequency f (hz) s=— 


I- amplitude (bytes) 




Figure 1. A Waveform 

There are many different types of waveforms, three of which are 
depicted in Figure 2. Sine waves are generated by objects that 
oscillate periodically at a single frequency (such as a guitar string). 
Square waves are generated by objects that toggle instantly between two 
states at a single frequency (such as a doorbell buzzer). Free-form 
waves are the most common waves of all, and are generated by all 




3/dd/84 Hacker 


CONFIDENTIAL 


/OS/SOUND. 2 



ABOUT THE SOUND DRIVER 


5 




objects that vibrate at rapidly changing frequencies with rapidly 
changing amplitudes (such as your vocal cords or the ^Instruments of an 
orchestra all playing at once). 



sine wave 





square w eve 





Figure 2. Types of Waveforms 

Figure 3 shows the analog representation of a waveform. The Sound 
Driver represents waveforms digitally, so all waveforms must be 
converted from their analog representation to a digital representation. 
The rows of numbers at the bottom of the figure are digital 
representations of the waveform. The numbers in the upper row are the 
amplitudes relative to the horizontal zero-amplitude line. The numbers 
in the lower row all represent the same relative amplitudes, but have 
been normalized to positive numbers. 
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Figure 3* Analog and Digital Representations of a Waveform 

A digital representation of a waveform is simply a sequence of wave 
amplitudes measured at fixed intervals* This sequence of amplitudes is 
stored in the Sound Driver as a sequence of bytes, each one of which 
specifies an instantaneous voltage to be sent to the speaker* The 
bytes are stored in a data structure called a waveform description * 
Since a sequence of bytes can only represent a group of numbers whose 
maximum and minimum values differ by less than 256, the amplitudes of 
your waveforms must be constrained to these same limits* 


SOUND DRIVER SYNTHESIZERS . 

A description of the sound to be generated by a synthesizer is 
contained in a data structure called a synthesizer buffer * A 
synthesizer buffer contains the duration, pitch, phase, and waveform of 
the sound the synthesizer will generate* The exact structure of a 
synthesizer buffer differs for each type of synthesizer being used* 


Free-Form Synthesizer 

The free-form synthesizer is used to synthesize complex music and 
speech* The sound to be produced is represented as a waveform whose 
complexity and length are limited only by available memory* 

A free-form synthesizer buffer consists of one integer and one long 
integer followed by a waveform description (Figure 4)* The waveform 
description can contain up to 256 bytes* Each amplitude in the 
waveform description will be generated once; when the end of the 
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waveform Is reached, the synthesizer will stop. The integer must be 0, 
to Identify the buffer as a free-form buffer* The deration long 
integer determines the length of time (in 44.93 usee increments) each 
amplitude in the waveform will be produced* The high-order word of the 
duration long integer contains the integral part and the low-order word 
contains the fractional part of the duration. (Binary fractions are 
described in the Toolbox Utilities manual under Fixed-Point Numbers.) 


The time interval specified by the duration long Integer can vary 
between 44.93 usee and 2.95 sec, corresponding to the binary fractions 
1.0000 (represented by the four bytes $00 01 00 00, or the long integer 
1) and 65535.9999 (represented by the four bytes $FF FF FF FF, or the 
long integer 4294967295), respectively. 


(note) 

As a further example, the time interval 89.86 usee 
corresponds to the binary fraction 2.0000, the four bytes 
$00 02 00 00, and the long integer 131072. The time 
interval .0115 sec corresponds to the binary fraction 
25*5000, the four bytes $00 19 80 00, and the long 
integer 1671168. 


duration 
long integer 




waveform 

bytes 


duration long integer 


1 

integral part 
1 


T 

fractional part 

I 




Figure 4. Free-Form Synthesizer Buffer 


Note that the duration long integer specifies a time 
interval, but it doesn't specify the period of a wave 
cycle* To determine the time period of a wave cycle in 
the waveform, use the following relationship: 

period =» time interval * wavelength 

where the wavelength is given in bytes. For example, the 
period of a wave of 10-byte wavelength with a time 
interval of 2 usec/byte would be 900 usee (corresponding 
to 1111 Hz). 


Assembly-language note : The address of the free-form buffer 
currently in use is contained in the system global soundBase. 




(note) 
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Square-Wave Synthesizer 


The square-wave synthesizer is used to make sounds such as beeps. A 
square-wave synthesizer buffer consists of a negative integer followed 
by a sequence of integer triplets (Figure 5). The negative integer 
identifies the buffer as a square-wave buffer. Each triplet contains 
the count, amplitude, and duration of a different sound. The square- 
wave synthesizer doesn’t require a waveform description because of the 
simple form of square waves. You can store as many triplets in a 
synthesizer buffer as there's room for. 


negative integer 


count integer 



amplitude integer 


- first sound 

duration integer 



> 2 


count integer 



amplitude integer 


- last sound 

duration integer 




Figure 5. Square-Wave Synthesizer Buffer 

Each count integer can range in value from 0 to 65535; the actual 
frequency the count corresponds to is given by the relationship: 

frequency (Hz) = 783360 / count 

A partial list of count values and corresponding frequencies for notes 
comprising Ptolemy’s diatonic scale (the scale to which pianos are 
tuned) is given in the summary at the end of this manual. 


Assembly— language note : The value of count currently in use is 
contained in the system global curPitch. 


Each amplitude integer can range from 0 to 255. Each duration integer 
specifies the number of ticks the sound will be generated, ranging from 
0 to 255 (corresponding to 0 to 4.25 seconds). 

The last sound triplet must be signified by a count integer of 0. When 
the square-wave synthesizer is used, the sound specified by each 
triplet is generated once, and then the synthesizer stops. 
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Four-Tone Synthesizer *_ 

The four-tone synthesizer Is used to produce harmonic sounds such as 
music. It can simultaneously generate four different sounds, each with 
Its own frequency, phase, and waveform. 

A four-tone synthesizer buffer consists of an Integer and a pointer 
(Figure 6). The integer can be any positive number, and serves only to 
identify the buffer as a four-tone buffer. The pointer points to a 
data structure describing the four tones, called a four-tone record. 


Assembly-language note : The address of the four-tone record 
currently In use is stored in the system global soundPtr. 




positive integer 


pointer to 4-tune record 

hC 

four-tone record 


Figure 6. Four-Tone Synthesizer Buffer 

A four-tone record consists of a duration integer followed by 12 long 
integers that contain the rate, phase, and pointers to the waveform 
descriptions of the four sounds (see Figure 7). 




duration integer 
sound 1 rate 
long integer 

sound 1 phase 
long integer 


/ z 


sound 4 rate 
long integer 

30und 4 phase 
long integer 

sound 1 

waveform pointer 


sound -4 

waveform pointer 


rate long 

integer 

not 

used 

integral 

punt 

l 

fracti onal pert 

1 


waveform descriptions 


c 

sound 1 

256 bytes 

a 



6 

t 

sound 4 

256 bytes 



Figure 7. Four-Tone Record 
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The duration integer indicates the number of ticks that each sound will 
be generated, from 0 to 255 (0 to 4-25 seconds). Ea dtx phase integer 
indicates the byte within the waveform description at which the 
synthesizer should begin producing sound (the first byte is byte number 
0). Each rate long Integer determines the speed at which the 
synthesizer cycles through the waveform. The low-order word of the 
rate long integer contains the fractional part of the rate, and the 
low-order byte of the high-order word contains the integral part. 
(Binary fractions are described in the Toolbox Utilities manual under 
Fixed-Point Numbers.) The rate long integer can vary between 0 and 
16777215. 

The waveform description for each tone must contain 256 bytes. The 
four-tone synthesizer creates sound by starting at the byte in the 
waveform description specified by the phase, and skipping rate bytes 
ahead every 44.93 usee; when the time specified by the duration integer 
has elapsed, the synthesizer stops. The amount of time required to 
cycle completely through the waveform is 16777216 * 44.93 usee / rate 
(11502 usee if the rate long integer is 65536 — corresponding to about 
87 Hz if the waveform contains one wavelength). If the waveform 
contains one wavelength, the frequency the rate corresponds to is given 
by 


frequency (Hz) = rate / 753.795 

The maximum rate of 16777215 corresponds to 44.93 usee, or about 22.3 
kHz if the waveform contains one wavelength, and a rate of 0 produces 
no sound. A partial list of rate values and corresponding frequencies 
for notes comprising Ptolemy* s diatonic scale (the scale to which 
pianos are tuned) isis given in the summary at the end of this manual. 


USING THE SOUND DRIVER 


The Sound Driver is a standard Macintosh device driver, and is 
manipulated via the Device Manager DriverOpen, DriverClose, Write, and 
Control calls. The Sound Driver doesn*t support Read or Status calls. 

The Sound Driver is automatically opened when the system starts up. 

Its driver name is .Sound, and its driver reference number is -4. To 
close the Sound Driver, call DriverClose(-4) ; you can reopen it by 
calling DriverOpen(**. Sound"). 

To use one of the three types of synthesizers to generate sound, use 
the Memory Manager routines NewHandle and SetHandleSize to allocate 
heap space for a synthesizer buffer. Then, fill the buffer with values 
describing the sound, and make an Write call to the Sound Driver. The 
Write parameters passed must be as follows: 

- RefNum must be -4. 

- BuffPtr must point to the synthesizer buffer. 
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f*S 








- Count must contain the length of the synthesizer buffer, in bytes. 

f 

When you use the free-form synthesizer, the amplitudes described by 
each byte in the waveform description are generated sequentially until 
the number of bytes specified by the count parameter have been written. 
When you use the square-wave synthesizer, the sounds described by each 
sound triplet are generated sequentially until either the end of the 
buffer has been reached (indicated by a count integer of 0 in the 
square-wave buffer), or the number of bytes specified by the Write 
call's count parameter have been written. When you use the four-tone 
synthesizer, all four sounds are generated for the length of time 
specified by the duration integer in the four-tone record. 

There are three different calls you can make to the Sound Driver's 
control routine: 

- Kill 10 is a standard control call supported by all drivers. It 
stops any sound currently being generated, and deletes all 
asynchronous I/O requests to the Sound Driver that haven't yet 
been processed. 

- SetVolume allows you to change the volume of the sound that passes 
through the Macintosh speaker. There are eight levels of volume, 
specified by the three low-order bits in the opParam parameter of 
the Control call, 0 being low, and 7 high. Applications shouldn't 
change the speaker volume, as it's really up to the user to choose 
the normal sound level via the Control Panel desk accessory. 

- Advanced Programmers: SetLevel enables you to control the 
amplitude of the sound generated by the square-wave synthesizer. 
The amplitude is contained in the opParam parameter of the Control 
call, and must be in the range 0 to 255. This call is explained 
in more detail below. 

When you call the Sound Driver's control routine, the parameters must 
contain the following: 

- RefNum must be -4. 

- OpCode must specify the type of call: 

Call OpCode 

Kill 10 1 

SetVolume 2 

SetLevel 3 

- OpParam must provide the volume level for a SetVolume call, and 
the amplitude for a SetLevel call. 

(note) 

Advanced programmers using low-level Pascal or 
assembly-language Device Manager routines must pass the 
above values in a parameter block. In addition, if 
you're calling the Sound Driver asynchronously, the 
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ioCompletion parameter must contain either the address of 
a completion routine or NIL. f 


Assembly~language note : The current speaker volume level is 
contained in the system global sdVolume* 


Advanced Control Routine 

The following paragraphs describe how the Sound Driver uses the 
Macintosh hardware to produce sound, and how you can intervene in the 
process to control the square-wave synthesizer. You can skip this 
section if it doesn't interest you, and you'll still be able to use the 
Sound Driver as described, except for the SetLevel call* 

To generate sound at the amplitude level specified by a square - wave 
synthesizer buffer, the Sound Driver places the value of the amplitude 
integer into a 740— byte buffer shared by both the Sound Driver and the 
disk-motor speed-control circuitry. Then, every 44.93 usee when the 
video beam wraps from the right edge of the screen to the left, the 
microprocessor automatically fetches an additional two bytes from this 
buffer. The high-order byte is sent to the speaker, and the low-order 
byte to the disk-motor speed-control circuitry* 


Assembly— language note s The amplitude level in the 740-byte 
buffer is contained in the system global soundLevel* 


(note) 

All the frequencies generated by the Sound Driver are 
multiples of this 44.93 usee period. The highest 
frequency the Sound Driver can physically generate 
corresponds to twice this period, 89*96 usee, or a 
frequency of 11116 Hz. 

You can cause the square-wave synthesizer to start generating sound, 
and then change the amplitude of the sound being generated any time you 
wish: 


1. Make an asynchronous Write call to the Sound Driver specifying the 
count, amplitude, and duration of the sound you want generated. 

The amplitude you specify will be placed in the 740-byte buffer, 
and the Sound Driver will begin producing sound* 
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2 . Whenever you want to change the sound being generated, make a 

Set Level call with the opParam parameter specif/Lng the amplitude 
of the new sound. The amplitude you specify will be placed in the 
740-byte buffer, and the sound will change. You can continue to 
change the sound until the time specified by the duration integer 
has elapsed. 
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SUMMARY OF THE SOUND DRIVER 




Free-Form Synthesizer Buffer 


duration 
long integer 


waveform 

bytes 


Square-Wave Synthesizer Buffer 


duration long integer 



negative integer 
count integer 
amplitude integer 
duration integer 

count integer 
amplitude integer 
duration integer 


first sound 


last sound 


Four-Tone Synthesizer Buffer 


positive integer 
pointer to 4-tone record 


four-tone record 
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Four-Tone Record 




Z 


deration integer 


sound 1 rate 
long integer 


sound 1 phase 
long integer 


/ 


rote long 

integer 

not 

used 

integral 

part 

— \ 
fractional part 
J 


sound 4 rate 
long integer 



sound 4 phase 
long integer 


waveform descriptions 

sound 1 


sound 1 

waveform pointer 


256 bytes 


Z 


sound 4 


sound 4 

waveform pointer 


256 bytes 


Sound Driver Control Calls 


Call 

KilllO 

SetVolume 

SetLevel 


OpCode 

1 

2 

3 


Assembly-Language Information 




Variables 


Sd Volume 
SoundPtr 
Sound Base 
Sound Level 
CurPitch 


; speaker volume level 
;pointer to four-tone record 
;pointer to free-form buffer 
; amplitude in 740-byte buffer 

;value of count in square-wave synthesizer buffer 
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Sound Driver Values For Notes Comprising Ptolemy's Dfatonic Scale 




Rate Values for the 

Count 

Values For the 



Four-Tone 

Synthesizer 

Square 

-Wave Synthesizer 

Note (Freqency) 

Lons Word 

Long Integer 

Word 

Integer 

3 octaves below 

middle C 




c 

(33) 

0000 612B 

24875 

5CBA 

23738 

Db 

(35.2) 

0000 67A5 

26533 

56EF 

22255 

D 

(37.125) 

0000 6D50 

27984 

526D 

21101 

Eb 

(39.6) 

0000 749A 

29850 

4D46 

19782 

E 

(41.25) 

0000 7976 

31094 

4A2F 

18991 

F 

(44) 

0000 818E 

33166 

458C 

17804 

Gb 

(46.9375) 

0000 8A35 

35381 

4131 

16689 

G 

(49.5) 

0000 91C0 

37312 

3DD1 

15825 

Ab 

(52.8) 

0000 9B78 

39800 

39F4 

14836 

A 

(55) 

0000 A1F2 

41458 

37A3 

14243 

Bb 

(57.75) 

0000 AA0B 

43531 

34FD 

13565 

B 

(61.875) 

0000 B631 

46641 

3174 

12660 

2 octaves below middle C 




C 

(66) 

0000 C256 

49750 

2E5D 

11869 

Db 

(70.4) 

0000 CF4B 

53067 

2B77 

11127 

D 

(74.25) 

0000 DAA1 

55969 

2936 

10550 

Eb 

(79.2) 

0000 E934 

59700 

26A3 

9891 

E 

(82.5) 

0000 F2EC 

62188 

2517 

9495 

F 

(88) 

0001 031D 

66333 

22C6 

8902 

Gb 

(93.875) 

0001 146A 

70762 

2099 

8345 

G 

(99) 

0001 2381 

74625 

1EE9 

7913 

Ab 

(105.6) 

0001 36F0 

79600 

1CFA 

7418 

A 

(110) 

0001 43E5 

82917 

1BD1 

7121 

Bb 

(115.5) 

0001 5417 

87063 

1A7E 

6782 

B 

(123.75) 

0001 6C62 

93282 

18BA 

6330 

1 octave below middle C 




c 

(132) 

0001 84 AC 

99500 

172F 

5935 

Db 

(140.8) 

0001 9E96 

106134 

15BC 

5564 

D 

(148.5) 

0001 B542 

111938 

149B 

5275 

Eb 

(158.4) 

0001 D269 

119401 

1351 

4945 

E 

(165) 

0001 E5D8 

124376 

128C 

4748 

F 

(176) 

0002 063B 

132667 

1163 

4451 

Gb 

(187.75) 

0002 28D5 

141525 

104C 

4172 

G 

(198) 

0002 4703 

149251 

0F74 

3956 

Ab 

(211.2) 

0002 6 DEI 

159201 

0E7D 

3709 

A 

(220) 

0002 87CA 

165834 

0DE9 

3561 

Bb 

(231) 

0002 A82E 

174126 

0D3F 

3391 

B 

(247.5) 

0002 D8C4 

186564 

0C5D 

3165 
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Middle C 


c 

(264) 

0003 0959 

199001 

0B97 « 

2967 

Db 

(281.6) 

0003 3D2C 

212268 

0ADE 

2782 

D 

(297) 

0003 6A85 

223877 

0A4E 

2638 

Eb 

(316.8) 

0003 A4D2 

238802 

09A9 

2473 

E 

(330) 

0003 CBB0 

248752 

0946 

2374 

F 

(352) 

0004 0C77 

265335 

08B1 

2225 

Gb 

(375.5) 

0004 51AA 

283050 

0826 

2086 

G 

(396) 

0004 8E06 

298502 

07BA 

1978 

Ab 

(422.4) 

0004 DBC3 

318403 

073F 

1855 

A 

(440) 

0005 0F95 

331669 

06F4 

1780 

Bb 

(462) 

0005 505D 

348253 

06A0 

1696 

B 

(495) 

0005 B188 

373128 

062F 

1583 

1 octave above 

middle C 




C 

(528) 

0006 12B3 

398003 

05CC 

1484 

Db 

(563.2) 

0006 7A59 

424537 

056F 

1391 

D 

(594) 

0006 D50A 

447754 

0527 

1319 

Eb 

(633.6) 

0007 49A4 

477604 

04D4 

1236 

E 

(660) 

0007 9760 

497504 

04A3 

1187 

F 

(704) 

0008 18EF 

530671 

0459 

1113 

Gb 

(751) 

0008 A354 

566100 

0413 

1043 

G 

(792) 

0009 1C0D 

597005 

03DD 

989 

Ab 

(844.8) 

0009 B786 

636806 

039F 

927 

A 

(880) 

000 A 1F2B 

663339 

037A 

890 

Bb 

(924) 

000 A A0BA 

696506 

0350 

848 

B 

(990) 

000B 6311 

746257 

0317 

791 

2 octaves above 

middle C 




C 

(1056) 

000C 2567 

796007 

02E6 

742 

Db 

(1126.4) 

000C F4B2 

849074 

02B7 

695 

D 

(1188) 

000D AA14 

895508 

0293 

659 

Eb 

(1267.2) 

000E 9349 

955209 

0 26A 

618 

E 

(1320) 

000 F 2EC1 

995009 

0251 

593 

F 

(1408) 

0010 31DF 

1061340 

022C 

556 

Gb 

(1502) 

0011 46 A8 

1132200 

020A 

522 

G 

(1584) 

0012 381B 

1194010 

01EF 

495 

Ab 

(1689.6) 

0013 6F0C 

1273610 

01D0 

464 

A 

(1760) 

0014 3E57 

1326680 

01BD 

445 

Bb 

(1848) 

0015 4175 

1393010 

01A8 

424 

B 

(1980) 

0016 C622 

1492510 

018C 

396 
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3 octaves above middle C 


c 

(2112) 

0018 4ACF 

1592020 

0173 • 

371 

Db 

(2252.8) 

0019 E965 

1698150 

015C 

348 

D 

(2376) 

001B 5429 

1791020 

014A 

330 

Eb 

(2534.4) . 

001D 2692 

1910420 

0135 

309 

E 

(2640) 

001E 5D83 

1990020 

0129 

297 

F 

(2816) 

0020 63BF 

2122690 

0116 

278 

Gb 

(3004) 

0022 8D50 

2264400 

0105 

261 

G 

(3168) 

0024 7036 

2388020 

00F7 

247 

Ab 

(3379.2) 

0026 DEI 8 

2547220 

00E8 

232 

A 

(3520) 

0028 7 CAE 

2653360 

00DF 

223 

Bb 

(3696) 

002A 82EA 

2786030 

00D4 

212 

B 

(3960) 

002D 8C44 

2985030 

00C6 

198 
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GLOSSARY 

amplitude: The vertical distance between any given point on a wave and 
the horizontal line about which the amplitude oscillates. 

four-tone record: A data structure describing the four tones produced 
by a four-tone synthesizer. 

four-tone synthesizer: The part of the Sound Driver used to make 
simple harmonic tones, with up to four "voices" producing sound 
simultaneously. 

free-form synthesizer: The part of the Sound Driver used to make 
complex music and speech. 

frequency: The number of cycles per second (also called Hertz) at 
which a wave oscillates. 

period: The time elapsed during one complete cycle of a wave. 

phase: Some fraction of a wave cycle (measured from a fixed point on 

the wave ) • 

square-wave synthesizer: The part of the Sound Driver used to produce 
less harmonic sounds such as beeps. 

synthesizer buffer: A description of the sound to be generated by a 
synthesizer. 

waveform: The physical shape of a wave. 

waveform description: A sequence of bytes describing a waveform, 
wavelength: The horizontal extent of one complete cycle of a wave. 
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File: ToolBox Names Page 1 

Report: TrapList Feb 8, 1984 

Selection: Value /Trap: equals A000 
through Value/Trap: equals FFFF 
Name: Value/ Fields: 


AddDrive 

A04E 

CopyRgn 

ACDC 

EraseArc 

ACCO 

AddPt 

AC7E 

Could Alert 

AD89 

EraseOval 

ACB9 

AddReference 

AD AC 

CouldDialog 

AD79 

ErasePoly 

ACC8 

Add Res Menu 

AD4D 

CountMItems 

AD50 

Erase Rect 

AC A3 

AddResource 

ADAB 

CountResources 

AD9C 

EraseRgn 

ACD4 

Alert 

AD85 

CountTypes 

AD9E 

Erase Round Rect 

ACB2 

AngleFromSlope 

ACC4 

CreateResFile 

ADB1 

Error Sound 

AD8C 

Append Menu 

AD33 

CurResFile 

AD94 

Event Avail 

AD71 

BackColor 

AC63 

Delay 

A03B 

ExitToShell 

ADF4 

BackPat 

AC7C 

DeleteMenu 

AD36 

FileAllocate 

A010 

BeginUpdate 

AD22 

DeltaPoint 

AD4F 

FileCreate 

A008 

Bit And 

AC58 

DeQueue 

AD6E 

File Delete 

AO 09 

BitClr 

AC5F 

De tachResouce 

AD92 

Fill Arc 

ACC2 

BitNot 

AC5A 

DialogSelect 

AD80 

FillOval 

ACBB 

BitOr 

AC5B 

DiffRgn 

ACE6 

Fill Poly 

ACCA 

BitSet 

AC5E 

Disableltem 

AD3A 

FillRect 

ACA5 

BitShift 

AC5C 

DisposeControl 

AD55 

FillRgn 

ACD6 

BitTst 

AC5D 

DisposeDialog 

AD83 

FillRoundRect 

ACB4 

BitXor 

AC59 

DisposeMenu 

AD32 

Find Control 

AD6C 

BlockMove 

A02E 

DisposePtr 

A01F 

FindWindow 

AD2C 

BringToFront 

AD20 

DisposeRgn 

ACD9 

FIni t Queue 

AO 16 

Button 

AD74 

DisposeWindow 

AD14 

FixMul 

AC68 

CalcMenuSize 

AD48 

DragControl 

AD67 

FixRatio 

AC69 

CalcVis 

ADO 9 

DragGrayRgn 

AD05 

FixRound 

AC6C 

CalcVisBehind 

ADOA 

DragTheRgn 

AD26 

Flash Menu Bar 

AD4C 

Caution Alert 

AD88 

DragWindow 

AD25 

FlushEvents 

A032 

Chain 

ADF3 

DrawChar 

AC83 

FlushFil 

A045 

Changed ResData 

ADAA 

DrawControls 

AD69 

FlushVol 

A013 

CharWidth 

AC8D 

DrawDialog 

AD81 

FMSwapFont 

AD01 

Checkltem 

AD45 

DrawGrowlcon 

ADO 4 

ForeColor 

AC62 

CheckUpDate 

AD11 

DrawMenuBar 

AD37 

Frame Arc 

ACBE 

ClearMenuBar 

AD34 

DrawNew 

ADOF 

FrameOval 

ACB7 

ClipAbove 

ADOB 

DrawPicture 

ACF6 

FramePoly 

ACC 6 

ClipRect 

AC7B 

DrawString 

AC84 

Frame Rect 

ACA1 

Close 

A001 

DrawText 

AC85 

Frame Rgn 

ACD2 

CloseDeskAcc 

ADB7 

Drvr Ins tall 

A03D 

Frame Round Rect 

AC BO 

CloseDialog 

AD82 

DrvrRemove 

A03E 

FreeAlert 

AD8A 

ClosePicture 

ACF4 

DsposeHandle 

AO 23 

Free Dialog 

AD7A 

ClosePoly 

ACCC 

Ej ect 

AO 17 

FreeMem 

AO 1C 

ClosePort 

AC7D 

EmptyHandle 

A02B 

FrontWindow 

AD24 

CloseResFile 

AD9A 

EmptyRect 

ACAE 

GetAppParms 

ADF5 

CloseRgn 

ACDB 

EmptyRgn 

ACE2 

GetClip 

AC7A 

CloseWindow 

AD2D 

Enable Item 

AD39 

GetCRefCon 

AD5A 

CmpString 

A03C 

EndUpdate 

AD23 

GetCTitle 

AD5E 

ColorBit 

AC64 

EnQueue 

AD6F 

GetCtlAction 

AD6A 

CompactMem 

A04C 

EqualPt 

AC81 

GetCtlMax 

AD62 

Control 

A004 

Equal Rect 

ACA6 

GetCtlMin 

AD61 

CopyBits 

ACEC 

EqualRgn 

ACE3 

GetCtl Value 

AD60 
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Selection: Value/Trap: equals A000 
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Name: 

Value/ 

Fields: 




GetCursor 

ADB9 

GetWTitle 

ADI 9 

Is Dialog Event 

AD7F 

GetDltem 

AD8D 

GetZone 

A01A 

KillControls 

AD56 

GetEOF 

AO 11 

GlobalToLocal 

AC71 

Kill 10 

A006 

GetFilelnfo 

AOOC 

GrafDevice 

AC72 

KillPicture 

ACF5 

GetFNum 

ADOO 

GrowWlndow 

AD2B 

KillPoly 

ACCD 

GetFontlnfo 

AC8B 

Hand And Hand 

ADE4 

Launch 

ADF2 

GetFontName 

ACFF 

Handle Zone 

A026 

Line 

AC92 

GetFPos 

A018 

HandToHand 

ADE1 

LineTo 

AC91 

GetHandleSize 

A025 

HideControl 

AD58 

LoadResource 

ADA2 

Get Icon 

ADBB 

HideCursor 

AC52 

Load Sc rap 

ADFB 

Getlnd Re source 

AD9D 

HidePen 

AC96 

LoadSeg 

ADFO 

GetlndType 

AD9F 

HideWindow 

ADI 6 

LocalToGlobal 

AC70 

Getltem 

AD46 

HiliteControl 

AD5D 

LongMul 

AC67 

Getltemlcon 

AD3F 

HiliteMenu 

AD38 

LoWord 

AC6B 

GetlteraMark 

AD43 

HillteWindow 

AD1C 

MapPoly 

ACFC 

GetltemStyle 

AD41 

Hi Word 

AC6A 

MapPt 

ACF9 

GetIText 

AD90 

HLock 

A029 

MapRect 

ACFA 

Get Keys 

AD76 

HNo Purge 

A04A 

MapRgn 

ACFB 

GetMenu 

ADBF 

HomeResFile 

ADA4 

MaxMem 

AO ID 

GetMenuBar 

AD3B 

H Purge 

A049 

MenuKey 

AD3E 

GetMHandle 

AD49 

HUnlock 

A02A 

MenuSelect 

AD3D 

Get Mouse 

AD72 

Info Sc rap 

ADF9 

ModalDialog 

AD91 

GetNamedResourc 

ADA1 

InitApplZone 

A02C 

Moov 

AC94 

GetNewControl 

ADBE 

InitCursor 

AC50 

MoreMasters 

A036 

GetNewDialog 

AD7C 

InitDialogs 

AD7B 

MountVol 

AOOF 

GetNewMBar 

ADCO 

InitFonts 

ACFE 

MoveControl 

AD59 

GetNewWindow 

ADBD 

InitGraf 

AC6E 

MovePortTo 

AC77 

GetNextEvent 

AD70 

Ini t Math 

ADE6 

MoveTo 

AC93 

GetOSEvent 

A031 

Ini tMenus 

AD30 

MoveWindow 

AD1B 

GetPattern 

ADB8 

Ini t Pack 

ADE5 

Hunger 

ADEO 

GetPen 

AC9A 

InitPort 

AC6D 

NewControl 

ADS 4 

GetPenState 

AC 98 

InitResources 

AD95 

NewDialog 

AD7D 

GetPicture 

AOBC 

InitUtil 

A03F 

NewMenu 

AD31 

GetPixel 

AC65 

InitWindows 

AD12 

NewPtr 

AO IE 

GetPort 

AC74 

Ini t Zone 

AO 19 

NewRgn 

ACD8 

GetPtrSize 

A021 

InsertMenu 

AD35 

NewString 

ADO 6 

GetResAttrs 

ADA6 

InsertResMenu 

AD51 

NewWindow 

AD13 

GetResFileAttrs 

ADF6 

InsetRect 

ACA9 

NoteAlert 

AD87 

GetResInfo 

ADA8 

Inset Rgn 

ACE1 

NWHandle 

A022 

GetResource 

ADAO 

Ins tallRDri vers 

A04F 

Obscure Cursor 

AC56 

Get Sc rap 

ADFD 

InvalRect 

AD28 

OffLine 

A035 

GetString 

ADBA 

InvalRgn 

AD27 

Of fsetPoly 

ACCE 

GetTrap Address 

A046 

InvertArc 

ACC1 

Off setRect 

ACA8 

GetVol 

AO 14 

Inver tOval 

ACBA 

Off setRgn 

ACEO 

GetVolInfo 

A007 

Invert Poly 

ACC9 

Open 

A000 

GetWindowPic 

AD2F 

InvertRect 

ACA4 

OpenDeskAcc 

ADB6 

GetWMgrPort 

AD10 

InvertRgn 

ACD5 

OpenPicture 

ACF3 

GetWRefCon 

ADI 7 

Inver tRoundRect 

ACB3 

OpenPoly 

ACCB 
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Selection: Value/Trap: equals A000 
through Value/Trap: equals FFFF 
Name: Value/ Fields: 


OpenPort 

AC6F 

ReAllocHandle 

A027 

SetOrigin 

AC78 

OpenResFile 

AD97 

Rec ove rHand le 

A028 

SetPenState 

AC99 

OpenRf 

AOOA 

RectlnRg 

ACE9 

SetPort 

AC73 

OpenRgn 

ACDA 

RectRgn 

ACDF 

SetPortBits 

AC75 

OSGvent Avail 

AO 30 

ReleaseRe source 

AD A3 

SetPt 

AC80 

PackO 

ADE7 

Rename 

AOOB 

SetPtrSize 

A020 

Packl 

ADE8 

ResError 

ADAF 

SetRect 

ACA7 

Pack2 

ADE9 

ResrvMem 

A040 

Set RectRgn 

ACDE 

Pack3 

ADEA 

Rmve Reference 

ADAE 

SetResAttrs 

ADA7 

Pack4 

ADEB 

RmveResource 

ADAD 

SetResFileAttrs 

ADF7 

Pack5 

ADEC 

RsrcZonelnlt 

AD96 

SetResInfo 

ADA9 

Pack6 

ADED 

RstFilLock 

A042 

SetResLoad 

AD9B 

Pack7 

ADEE 

Save Old 

ADOE 

SetResPurge 

AD93 

PackBits 

ACCF 

ScalePt 

ACF8 

SetStdProcs 

ACEA 

PaintArc 

ACBF 

ScrollRect 

ACEF 

SetStrlng 

ADO 7 

PalntBehlnd 

ADOD 

SectRect 

ACAA 

SetTrapAddress 

A047 

PaintOne 

ADOC 

SectRgn 

ACE4 

SetVol 

AO 15 

PaintOval 

ACB8 

SelectWindow 

AD1F 

SetUindowPic 

AD2E 

PaintPoly 

ACC 7 

Send Behind 

AD21 

SetWRefCon 

AD18 

PaintRect 

ACA2 

SetApplBase 

AC57 

SetWTitle 

AD1A 

PaintRgn 

ACD3 

SetApplLimit 

A02D 

Set Zone 

AO IB 

PaintRoundRect 

ACB1 

SetClip 

AC79 

ShieldCursor 

AC55 

ParamText 

AD8B 

SetCRefCon 

AD5B 

ShowControl 

AD57 

PenMode 

AC9C 

SetCTitle 

AD5F 

ShowCursor 

AC53 

PenNormal 

AC9E 

SetCtlAction 

AD6B 

ShowHlde 

AD08 

PenPat 

AC9D 

SetCtlMax 

AD65 

ShowPen 

AC97 

PenSize 

AC9B 

SetCtlMin 

AD64 

ShowWindow 

AD15 

PlcComment 

ACF2 

SetCtlValue 

AD63 

SizeControl 

AD5C 

PlnRect 

AD4E 

SetCursor 

AC51 

SizeRsrc 

ADA5 

Plotlcon 

AD4B 

SetDateTime 

A03A 

SizeWindow 

AD1D 

PortSize 

AC76 

SetDItem 

AD8E 

SlopeFromAngle 

ACBC 

PostEvent 

A02F 

SetEmptyRgn 

ACDD 

SpaceExtra 

AC8E 

Pt2Rect 

ACAC 

Set EOF 

A012 

Status 

A005 

PtlnRect 

ACAD 

Set File Info 

AOOD 

StdArc 

ACBD 

PtlnRgn 

ACE8 

SetFilLock 

A041 

StdBits 

ACEB 

PtrAndHand 

ADEF 

SetFilType 

A043 

StdComment 

ACF1 

PtrToHand 

ADE3 

SetFontLock 

ADO 3 

StdGetPic 

ACEE 

PtrToXHand 

ADE2 

SetFPos 

AO 44 

StdLine 

AC90 

PtrZone 

A048 

SetGrowZone 

A04B 

StdOval 

ACB6 

PtToAngle 

ACC3 

SetHandleSize 

AO 24 

StdPoly 

ACC 5 

PurgeMem 

A04D 

Setltem 

AD47 

StdPutPic 

ACFO 

Put Icon 

ADCA 

Setltemlcon 

AD40 

StdRect 

ACAO 

Put Sc rap 

ADFE 

SetltemMark 

AD44 

StdRgn 

ACD1 

Random 

AC61 

SetltemStyle 

AD42 

StdRRect 

ACAF 

Read 

A002 

SetIText 

AD7E 

StdText 

AC82 

ReadDateTime 

A039 

SetIText 

AD8F 

StdTxMeasure 

ACED 

ReadParam 

A037 

Set Menu Bar 

AD3C 

StillDown 

AD73 

RealFont 

ADO 2 

Se t MenuFlash 

AD4A 

StopAlert 

AD86 
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through Value/Trap: equals FFFF 
Name: Value/ Fields: 


StringWidth 

AC 8 C 

Stuff Hex 

AC 66 

SubPt 

AC7F 

SystemBeep 

ADC 8 

SystemClick 

ADB3 

SystemEdit 

ADC 2 

SystemError 

ADC 9 

SystemEvent 

ADB2 

SystemMenu 

ADB5 

SystemTask 

ADB4 

TEActivate 

ADD 8 

TECalText 

ADDO 

TEClick 

ADD4 

TECopy 

ADD5 

TECut 

ADD 6 

TEDeactivate 

ADD9 

TEDelete 

ADD7 

TE Dispose 

ADCD 

TeGetText 

ADCB 

TEIdle 

ADDA 

TEInit 

ADCC 

TE Insert 

ADDE 

TEKey 

ADDC 

TENew 

ADD2 

TEPaste 

ADDB 

TEScroll 

ADDD 

TESetJust 

ADDF 

TESetSelect 

ADD1 

TESetText 

ADCF 

TestControl 

AD 66 

TEUpdate 

ADD3 

TextBox 

ADCE 

TextFace 

AC 88 

TextFont 

AC87 

Text Mode 

AC89 

TextSize 

AC 8 A 

TextWidth 

AC 86 

TickCount 

AD75 

TrackControl 

AD 68 

TrackGoAway 

AD1E 

UnionRect 

ACAB 

UnionRgn 

ACE5 

Unique ID 

ADC1 

Unload Scrap 

ADFA 

UnLoadSeg 

ADF1 

UnmountVol 

AOOE 

UnPackBits 

ACDO 

UpdateResFile 

AD99 


UprString 

AC54 

UseResFile 

AD98 

ValidRect 

AD2A 

ValidRgn 

AD29 

VInstall 

AO 33 

VRemove 

A034 

WaitMouseUp 

AD77 

Write 

AQ03 

WriteParam 

A038 

WriteResource 

ADBO 

XOrRgn 

ACE7 

ZeroScrap 

ADFC 


Feb 


Page 4 
8 , 1984 


File: ToolBox Names 

Report: TrapList 

Selection: Value/Trap: equals A000 
through Value/Trap: equals AFFF 


Value/ Name: 

Fields : 



A000 

Open 

AO 30 

OSEvent Avail 

AC61 

A001 

Close 

A031 

GetOSEvent 

AC62 

A002 

Read 

A032 

FlushEvents 

AC63 

A003 

Write 

A033 

VInstall 

AC64 

A004 

Control 

A034 

VRemove 

AC65 

A005 

Status 

A035 

Off Line 

AC66 

A006 

Kill 10 

A036 

MoreMasters 

AC 6 7 

A007 

GetVollnfo 

A037 

ReadParam 

AC68 

A008 

FileCreate 

A038 

Write Param 

AC69 

A009 

File Delete 

A039 

ReadDateTime 

AC6A 

AOOA 

OpenRf 

A03A 

SetDateTime 

AC6B 

AOOB 

Rename 

A03B 

Delay 

AC6C 

AOOC 

GetFilelnfo 

A03C 

CmpString 

AC6D 

AOOD 

SetFtlelnfo 

A03D 

Drvr Ins tall 

AC6E 

AOOE 

UnmountVol 

A03E 

DrvrRemove 

AC6F 

AOOF 

MountVol 

A03F 

InitUtil 

AC70 

AO 10 

FileAllocate 

A040 

ResrvMem 

AC71 

A011 

GetEOF 

A041 

SetFilLock 

AC72 

A012 

Set EOF 

A042 

RstFilLock 

AC73 

A013 

FlushVol 

A043 

SetFilType 

AC74 

AO 14 

GetVol 

A044 

SetFPos 

AC75 

A015 

SetVol 

A045 

FlushFil 

AC76 

A016 

FInitQueue 

A046 

GetTrapAddress 

AC77 

A017 

Eject 

A047 

SetTrapAddress 

AC78 

A018 

GetFPos 

A048 

PtrZone 

AC79 

A019 

Ini t Zone 

A049 

HPurge 

AC7A 

A01A 

Get Zone 

A04A 

HNoPurge 

AC7B 

A01B 

SetZone 

A04B 

SetGrowZone 

AC7C 

A01C 

FreeMem 

A04C 

Compact Mem 

AC7D 

A01D 

MaxMem 

A04D 

PurgeMem 

AC7E 

A01E 

NewPtr 

A04E 

AddDrive 

AC7F 

A01F 

DisposePtr 

A04F 

Ins tallRDri vers 

AC80 

A020 

SetPtrSize 

AC50 

InitCursor 

AC81 

A021 

GetPtrSize 

AC51 

SetCursor 

AC82 

A022 

NWHandle 

AC52 

HideCursor 

AC83 

A023 

DsposeHandle 

AC53 

ShowCursor 

AC84 

AO 24 

SetHandleSize 

AC54 

UprString 

AC85 

A025 

GetHandleSize 

AC55 

ShieldCursor 

AC86 

A026 

HandleZone 

AC56 

ObscureCursor 

AC87 

A027 

ReAllocHandle 

AC57 

SetApplBase 

AC88 

A028 

Recove rHandle 

AC58 

Bit And 

AC89 

A029 

HLock 

AC59 

BitXor 

AC8A 

AO 2 A 

HUnlock 

AC5A 

BitNot 

AC8B 

A02B 

Empty Handle 

AC5B 

BitOr 

AC8C 

A02C 

InitApplZone 

AC5C 

BitShif t 

AC8D 

A02D 

SetApplLimit 

AC5D 

BitTst 

AC8E 

A02E 

BlockMove 

AC5E 

BitSet 

AC 90 

A02F 

PostEvent 

AC5F 

BitClr 

AC91 
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Random 

ForeColor 

BackCo lor 

Color Bit 

GetPixel 

StuffHex 

Long Mu 1 

FixMul 

FixRatio 

HiWord 

LoWord 

FixRound 

InitPort 

InitGraf 

OpenPort 

LocalToGlobal 

GlobalToLocal 

GrafDevice 

SetPort 

Get. Port 

SetPortBits 

PortSize 

MovePortTo 

SetOrigin 

SetClip 

GetClip 

ClipRect 

BackPat 

ClosePort 

AddPt 

SubPt 

SetPt 

EqualPt 

StdText 

DrawChar 

DrawString 

DrawText 

TextWidth 

TextFont 

Text Face 

TextMode 

TextSize 

GetFontlnfo 

StringWidth 

CharWidth 

SpaceExtra 

StdLine 

LineTo 



File: ToolBox Names Page 2 

Report: TrapList Pab 8, 19^^, 

Selection: Value/Trap: equals A000 - 

through Value/Trap: equals AFFF 
Value/ Name: Fields: 


AC92 

Line 

ACC5 

StdPoly 

ACF6 

DrawPicture 

AC93 

MoveTo 

ACC6 

FramePoly 

ACF8 

ScalePt 

AC94 

Moov 

ACC7 

PaintPoly 

ACF9 

MapPt 

AC96 

HidePen 

ACC8 

ErasePoly 

ACFA 

Map Rect 

AC97 

ShowPen 

ACC9 

InvertPoly 

ACFB 

MapRgn 

AC98 

GetPenState 

ACCA 

Fill Poly 

ACFC 

MapPoly 

AC 99 

SetPenState 

ACCB 

OpenPoly 

ACFE 

InitFonts 

AC9A 

GetPen 

ACCC 

ClosePoly 

ACFF 

Get Font Name 

AC9B 

PenSize 

ACCD 

KillPoly 

ADOO 

GetFNum 

AC9C 

PenMode 

ACCE 

Off set Poly 

AD01 

FMSwapFont 

AC9D 

PenPat 

ACCF 

PackBits 

AD02 

RealFont 

AC9E 

PenNormal 

ACDO 

UnPackBits 

ADO 3 

SetFontLock 

ACAO 

StdRect 

ACD1 

StdRgn 

AD04 

DrawGrowIcon 

ACA1 

FrameRect 

ACD2 

Frame Rgn 

ADO 5 

DragGrayRgn 

ACA2 

PaintRect 

ACD3 

PaintRgn 

ADO 6 

NewString ^ 

AC A3 

EraseRect 

ACD4 

EraseRgn 

AD07 

SetString 

ACA4 

InvertRect 

ACD5 

Invert Rgn 

AD08 

ShowHide 

ACA5 

FillRect 

ACD6 

FillRgn 

AD09 

CalcVis 

ACA6 

EqualRect 

ACD8 

NewRgn 

ADO A 

Cal cVis Behind 

ACA7 

SetRect 

ACD9 

DisposeRgn 

ADOB 

ClipAbove 

ACA8 

Off setRect 

ACDA 

OpenRgn 

ADOC 

PaintOne 

ACA9 

InsetRect 

ACDB 

CloseRgn 

ADOD 

PaintBehind 

ACAA 

SectRect 

AC DC 

CopyRgn 

ADOE 

SaveOld 

ACAB 

UnionRect 

ACDD 

Set Empty Rgn 

ADOF 

DrawNew 

ACAC 

Pt2Rect 

ACDE 

SetRectRgn 

AD10 

GetWMgrPort 

ACAD 

PtlnRect 

ACDF 

Rect Rgn 

AD11 

CheckUpDate 

ACAE 

EmptyRect 

ACEO 

Off setRgn 

ADI 2 

InitWindows 

ACAF 

StdRRect 

ACE1 

Inset Rgn 

AD13 

NewWindow 

ACBO 

Fr ame Round Rect 

ACE2 

Empty Rgn 

ADI 4 

DisposeWindow 

ACB1 

Pain t Round Rect 

ACE3 

EqualRgn 

AD15 

ShowWindow 

ACB2 

EraseRoundRect 

ACE4 

SectRgn 

ADI 6 

HideWindow 

ACB3 

Inver tRoundRect 

ACE5 

UnionRgn 

AD17 

GetWRefCon 

ACB4 

Fill Round Rect 

ACE6 

DiffRgn 

AD18 

SetWRefCon 

ACB6 

StdOval 

ACE7 

XOrRgn 

AD19 

GetWTitle 

ACB7 

FrameOval 

ACE8 

PtlnRgn 

AD1A 

SetWTitle 

ACB8 

PaintOval 

ACE9 

RectlnRg 

AD1B 

Move Window 

ACB9 

EraseOval 

ACEA 

SetStdProcs 

AD1C 

HiliteWindow 

ACBA 

InvertOval 

ACEB 

StdBits 

AD1D 

SizeWindow 

ACBB 

FillOval 

ACEC 

CopyBits 

AD1E 

TrackGoAway 

ACBC 

SlopeFromAngle 

ACED 

StdTxMeasure 

AD1F 

SelectWindow 

ACBD 

StdArc 

ACEE 

StdGetPic 

AD20 

BringToFront 

ACBE 

FrameArc 

ACEF 

Sc roll Rect 

AD21 

Send Behind 

ACBF 

PaintArc 

ACFO 

StdPutPic 

AD22 

BeginUpdate 

ACCO 

EraseArc 

ACF1 

StdComment 

AD23 

EndUpdate 

ACC1 

InvertArc 

ACF2 

PicComment 

AD24 

FrontWindow 

ACC2 

Fill Arc 

ACF3 

OpenPicture 

AD25 

DragWindow 

ACC 3 

PtToAngle 

ACF4 

ClosePicture 

AD26 

DragTheRgn 

ACC4 

AngleFromSlope 

ACF5 

Kill Picture 

AD27 

InvalRgn 
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Value/ Name: 

Fields: 



AD28 

InvalRect 

AD5A 

GetCRefCon 

AD8D 

AD29 

ValidRgn 

AD5B 

SetCRefCon 

AD8E 

AD2A 

ValidRect 

AD5C 

SizeControl 

AD8F 

AD2B 

GrowWindow 

AD5D 

HiliteControl 

AD90 

AD2C 

FindWindow 

AD5E 

GetCTitle 

AD91 

AD2D 

CloseWindow 

AD5F 

SetCTitle 

AD92 

AD2E 

SetWindowPic 

AD60 

GetCtlValue 

AD93 

AD2F 

GetWindowPic 

AD61 

GetCtlMin 

AD94 

AD30 

InitMenus 

AD62 

GetCtlMax 

AD95 

AD31 

NewMenu 

AD63 

SetCtlValue 

AD96 

AD32 

DisposeMenu 

AD64 

SetCtlMin 

AD97 

AD33 

AppendMenu 

AD65 

SetCtlMax 

AD98 

AD34 

ClearMenuBar 

AD66 

TestControl 

AD99 

AD35 

Insert Menu 

AD67 

DragControl 

AD9A 

AD36 

DeleteMenu 

AD68 

TrackControl 

AD9B 

AD37 

DrawMenuBar 

AD69 

DrawControls 

AD9C 

AD38 

HiliteMenu 

AD6A 

GetCtlAction 

AD9D 

AD39 

Enable Item 

AD6B 

SetCtlAction 

AD9E 

AD3A 

Disableltem 

AD6C 

FindControl 

AD9F 

AD3B 

Get Menu Bar 

AD6E 

De Queue 

AD AO 

AD3C 

SetMenuBar 

AD6F 

EnQueue 

ADA1 

AD3D 

MenuSelect 

AD70 

GetNextEvent 

ADA2 

AD3E 

MenuKey 

AD71 

Event Avail 

AD A3 

AD3F 

Getltemlcon 

AD72 

GetMouse 

ADA4 

AD40 

Setltemlcon 

AD73 

StillDown 

ADA5 

AD41 

GetltemStyle 

AD74 

Button 

ADA6 

AD42 

SetltemStyle 

AD75 

TickCount 

ADA7 

AD43 

GetltemMark 

AD76 

GetKeys 

ADA8 

AD44 

SetltemMark 

AD77 

Wait MouseUp 

ADA9 

AD45 

Checkltem 

AD79 

CouldDialog 

ADAA 

AD46 

Get Item 

AD7A 

FreeDialog 

ADAB 

AD47 

Set Item 

AD7B 

InitDialogs 

AD AC 

AD48 

CalcMenuSize 

AD7C 

GetNewDialog 

ADAD 

AD49 

GetMHandle 

AD7D 

NewDialog 

ADAE 

AD4A 

SetMenuFlash 

AD7E 

SetIText 

ADAF 

AD4B 

Plotlcon 

AD7F 

IsDialogEvent 

ADBO 

AD4C 

FlashMenuBar 

AD80 

Dialog Select 

ADB1 

AD4D 

AddResMenu 

AD81 

DrawDialog 

ADB2 

AD4E 

PinRect 

AD82 

CloseDialog 

ADB3 

AD4F 

DeltaPoint 

AD83 

DisposeDialog 

ADB4 

AD50 

CountMItems 

AD85 

Alert 

ADB5 

AD51 

InsertResMenu 

AD86 

StopAlert 

ADB6 

AD54 

NewControl 

AD87 

NoteAlert 

ADB7 

AD55 

DisposeControl 

AD88 

CautionAlert 

ADB8 

AD56 

KillControls 

AD89 

CouldAlert 

ADB9 

AD57 

ShowControl 

AD8A 

FreeAlert 

ADBA 

AD58 

HideControl 

AD8B 

ParamText 

ADBB 

AD59 

MoveControl 

AD8C 

ErrorSound 

ADBC 


Page 3 
Feb 8, 1984 


GetDItem 

SetDltem 

SetIText 

GetlText 

ModalDialog 

De tachResouce 

SetResPurge 

CurResFile 

InitResources 

RsrcZonelnit 

OpenResFile 

UseResFile 

UpdateResFile 

CloseResFile 

SetResLoad 

CountRe sources 

GetlndRe source 

CountTypes 

GetlndType 

GetResource 

GetNamedResourc 

Load Resource 

ReleaseResource 

HomeResFile 

SizeRsrc 

GetResAttrs 

SetResAttrs 

Get Res Info 

SetResInfo 

ChangedResData 

AddResource 

AddReference 

RmveResource 

RmveReference 

ResError 

WriteResource 

CreateResFile 

SystemEvent 

SystemClick 

SystemTask 

SystemMenu 

OpenDeskAcc 

CloseDeskAcc 

GetPattern 

GetCursor 

GetString 

Get Icon 

GetPicture 
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through Value/Trap: equals AFFF 


Value/ Name: 

Fields: 


ADBD 

GetNewWindow 

ADF2 

Launch 

ADBE 

GetNewControl 

ADF3 

Chain 

ADBF 

Get Menu 

ADF4 

ExitToShell 

ADCO 

GetNewMBar 

ADF5 

GetAppParms 

ADC1 

Unique ID 

ADF6 

GetResFileAttrs 

ADC2 

SystemEdit 

ADF7 

SetResFileAttrs 

ADC8 

SystemBeep 

ADF9 

InfoScrap 

ADC9 

SystemError 

ADFA 

Unload Sc rap 

ADCA 

Putlcon 

ADFB 

Load Sc rap 

ADCB 

TeGetText 

ADFC 

ZeroScrap 

ADCC 

TEInit 

ADFD 

GetScrap 

ADCD 

TEDispose 

ADFE 

Put Sc rap 


ADCE Text Box 

ADCF TESetText 
ADDO TECalText 
ADD1 TESetSelect 
ADD2 TENew 
ADD3 TEUpdate 
ADD4 TEClick 
ADDS TECopy 
ADD6 TECut 
ADD7 TEDelete 
ADD8 TEActivate 
ADD9 TEDeactivate 
ADDA TEIdle 
ADDB TEPaste 
ADDC TEKey 
ADDD TEScroll 
ADDE TE Insert 
ADDF TESetJust 
ADEO Munger 
ADE1 HandToHand 
ADE2 PtrToXHand 
ADE3 PtrToHand 
ADE4 HandAndHand 
ADE5 InitPack 
ADE6 Ini t Math 

ADE7 PackO 
ADE8 Packl 
ADE9 Pack2 
ADEA Pack3 
ADEB Pack4 
ADEC Pack5 
ADED Pack6 
ADEE Pack7 
ADEF Ptr And Hand 
ADFO LoadSeg 
ADF1 UnLoadSeg 
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Date: 3 October 1983 


To: Mac Developers 

Re: Mac serial connector pinout 


1 

- GND 


2 

- +5 

(may 

3 

- GND 


4 

- TXD+ 


5 

- TXD- 


6 

- +12 

(for 

7 

- HSK 

(CTS 


8 - RXD+ 

9 - RXD- 


turn into an output handshake line— don't use!) 


detecting power on ONLY!) 
or TRxC, depending on 8530 mode) 


For more-or-less RS232, use GND, TXD-, RXD-. The TXD+ and RXDf 
signals provide RS422/423 compatibility* 

The HSK (handshake) line (an input) connects to both CTS and to 
TRxC on the 8530. It can be used either for CTS, or for external 
clock depending on the mode the 8530 is in. As RS232 handshake, 
it usually connects to pin 20 on a DB-25. 


For the Exceedingly Curious... 

Signal lines go through a "deglitch" network, which is a "T" 
consisting of 25-50 ohm resistors and 200 pf to ground. 

We use 26LS30 and 26LS32 interface chips between the 8530 SCC and 
the outside world. 

The 8530 Data Carrier Detect lines (*DCDA pin 19 and *DCDB pin 21) 
are used as mouse inputs and generate interrupts used to detect 
mouse motion (!!!). 

The Mouse Pinout 

1 - GND 

2 - +5 (Mouse ONLY!) 

3 - GND 

4 - X2 (to 6522 PB4) 

5 - XI (to 8530 *DCDA) 

6 - No connect 

7 - *SW (to 6522 PB3) 

8 - Y2 (to 6522 PB5) 

9 - Y1 (to 8530 *DCDB) 


Bob Martin 
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ABSTRACT 

This document describes the QuickDraw graphics package, heart of the 
Macintosh User Interface Toolbox routines. It describes the conceptual 
and physical data types used by QuickDraw and gives details of the 
procedures and functions available in QuickDraw. 


Summary of significant changes and additions since last version: 

- "Font** no longer includes type size. There is a new grafPort 
field (txSize) and a procedure (TextSize) for specifying the size 
(pages 25, 43). Some other grafPort fields were reordered and 
some global variables were moved to the grafPort (page 18). 

- The character style data type was renamed Style and now includes 
two new variations, condense and extend (page 23). 

- You can set up your application now to produce color output when 
devices supporting it are available in the future (pages 30, 45). 

- The Polygon data type was changed (page 33), and the PolyNext 
procedure was removed. 

- There are two new grafPort routines, InitPort and ClosePort (pages 
35, 36), and three new calculation routines, EqualRect and 
EmptyRect (page 48) and EqualPt (page 65). 

- XferRgn and XferRect were removed; use CopyBits, PaintRgn, 

FillRgn, PaintRect , or FillRect. CursorVis was also removed; use 
HideCursor or ShowCursor. 

- A section on customizing QuickDraw operations was added (page 70). 
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ABOUT THIS MANUAL 


This manual describes QuickDraw, a set of graphics procedures, 
functions, and data types that allow a Pascal or assembly-language 
programmer of Macintosh to perform highly complex graphic operations 
very easily and very quickly. It covers the graphic concepts behind 
QuickDraw, as well as the technical details of the data types, 
procedures, and functions you will use in your programs. 

( hand ) 

This manual describes version 2.1 of the ROM. In earlier 
versions, QuickDraw may not work as discussed here. 

We assume that you are familiar with the Macintosh User Interface 
Guidelines, Lisa Pascal, and the Macintosh Operating System's memory 
management. This graphics package is for programmers, not end users. 
Although QuickDraw may be used from either Pascal or assembly language, 
this manual gives all examples in their Pascal form, to be clear, 
concise, and more intuitive; a section near the end describes the 
details of the assembly- language interface to QuickDraw. 

The manual begins with an introduction to QuickDraw and what you can do 
with it. It then steps back a little and looks at the mathematical 
concepts that form the foundation for QuickDraw: coordinate planes, 
points, and rectangles. Once you understand these concepts, read on 
about the graphic entities based on those concepts — how the 
mathematical world of planes and rectangles is translated into the 
physical phenomena of light and shadow. 

Then comes some discussion of how to use several graphics ports, a 
summary of the basic drawing process, and a discussion of two more 
parts of QuickDraw, pictures and polygons. 

Next, there's the detailed description of all QuickDraw procedures and 
functions, their parameters, calling protocol, effects, side effects, 
and so on — all the technical information you'll need each time you 
write a program for Macintosh. 

Following these descriptions are sections that will not be of interest 
to all readers. Special information is given for programmers who want 
to customize QuickDraw operations by overriding the standard drawing 
procedures, and for those who will be using QuickDraw from assembly 
language . 

Finally, there's a summary of the QuickDraw data structures and routine 
calls, for quick reference, and a glossary that explains terms that may 
be unfamiliar to you. 
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ABOUT QUICKDRAW 


QuickDraw allows you to divide the Macintosh screen into a number of 
individual areas. Within each area you can draw many things, as 
illustrated in Figure 1. 
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Figure 1. Samples of QuickDraw's Abilities 


You can draw: 

“ Text characters in a number of proportionally-spaced fonts, with 
variations that include boldfacing, italicizing, underlining, and 
outlining. 

- Straight lines of any length and width. 

- A variety of shapes, either solid or hollow, including: 
rectangles, with or without rounded corners; full circles and 
ovals or wedge-shaped sections; and polygons. 

- Any other arbitrary shape or collection of shapes, again either 
solid or hollow. 


- A picture consisting of any combination of the above items, with 
just a single procedure call. 

In addition, QuickDraw has some other abilities that you won't find in 
many other graphics packages. These abilities take care of most of the 
housekeeping" — the trivial but time-consuming and bothersome 
overhead that's necessary to keep things in order. 

- The ability to define many distinct "ports" on the screen, each 
with its own complete drawing environment — its own coordinate 
system, drawing location, character set, location on the screen, 
and so on. You can easily switch from one such port to another. 
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- Full and complete M clipping ,, to arbitrary areas, so that drawing 
will occur only where you want. It's like a super-duper coloring 
book that won't let you color outside the lines. You don't have 
to worry about accidentally drawing over something else on the 
screen, or drawing off the screen and destroying memory. 

- Off-screen drawing. Anything you can draw on the screen, you can 
draw into an off-screen buffer, so you can prepare an image for an 
output device without disturbing the screen, or you can prepare a 
picture and move it onto the screen very quickly. 

And QuickDraw lives up to its name! It's very fast. The speed and 
responsiveness of the Macintosh user interface is due primarily to the 
speed of the QuickDraw package. You can do good-quality animation, 
fast interactive graphics, and complex yet speedy text displays using 
the full features of QuickDraw. This means you don't have to bypass 
the general-purpose QuickDraw routines by writing a lot of special 
routines to improve speed. 


How To Use QuickDraw 

QuickDraw can be used from either Pascal or MC68000 machine language. 

It has no user interface of its own; you must write and compile (or 
assemble) a Pascal (or assembly-language) program that includes the 
proper QuickDraw calls, link the resulting object code with the 
QuickDraw code, and execute the linked object file. 

Some programming models are available through your Macintosh software 
coordinator; they show the structure of a properly organized QuickDraw 
program. What's best for beginners is to obtain a machine-readable 
version of the text of one of these programs, read through the text, 
and, using the superstructure of the program as a "shell", modify it to 
suit your own purposes. Once you get the hang of writing programs 
inside the presupplied shell, you can work on changing the shell 
itself. 

QuickDraw is stored permanently in the ROM memory. All access is made 
through an indirection table in low RAM. When you write a program that 
uses QuickDraw, you link it with this indirection table. Each time you 
call a QuickDraw procedure or function, or load a predefined constant, 
the request goes through the table into QuickDraw. You'll never access 
any QuickDraw address directly, nor will you have to code constant 
addresses into your program. The linker will make sure all address 
references get straightened out. 

QuickDraw is an independent unit; it doesn't use any other units, not 
even HeapZone (the Pascal interface to the Operating System's memory 
management routines). This means it cannot use the data types Ptr and 
Handle, because they are defined in HeapZone. Instead, QuickDraw 
defines two data types that are equivalent to Ptr and Handle, QDPtr and 
QDHandle. 
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TYPE QDByte = -128.. 127; 

QDPtr = "QDByte; 

QDHandle = "QDPtr; 

QuickDraw includes only the graphics and utility procedures and 

functions you'll need to create graphics on the screen. Keyboard 
input, mouse input, and larger user-interface constructs such as 
windows and menus are implemented in separate packages that use 
QuickDraw but are linked in as separate units. You don't need these 
units in order to use QuickDraw; however, you'll probably want to read 
the documentation for windows and menus and learn how to use them with 
your Macintosh programs. 


THE MATHEMATICAL FOUNDATION OF QUICKDRAW 

To create graphics that are both precise and pretty requires not 
supercharged features but a firm mathematical foundation for the 
features you have. If the mathematics that underlie a graphics package 
are imprecise or fuzzy, the graphics will be, too. QuickDraw defines 
some clear mathematical constructs that are widely used in its 
procedures, functions, and data types: the coordinate plane , the 
point, the rectangle , and the region . 


The Coordinate Plane — 

All Information about location, placement, or movement that you give to 
QuickDraw is in terms of coordinates on a plane. The coordinate plane 
is a two-dimensional grid, as illustrated in Figure 2. 


-32768 



4 r 

32767 

Figure 2. The Coordinate Plane 

There are two distinctive features of the QuickDraw coordinate plane: 
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- All grid coordinates are integers. 

- All grid lines are infinitely thin. 

These concepts are important! First, they mean that the QuickDraw 
plane is finite, not infinite (although it's very large). Horizontal 
coordinates range from -32768 to +32767, and vertical coordinates have 
the same range. (An auxiliary package is available that maps real 
Cartesian space, with X, Y, and Z coordinates, onto QuickDraw's 
two-dimensional integer coordinate system.) 

Second, they mean that all elements represented on the coordinate plane 
are mathematically pure. Mathematical calculations using integer 
arithmetic will produce intuitively correct results. If you keep in 
mind that grid lines are infinitely thin, you'll never have "endpoint 
paranoia" — the confusion that results from not knowing whether that 
last dot is included in the line. 


Points 


On the coordinate plane are 4,294,967,296 unique points. Each point is 
at the intersection of a horizontal grid line and a vertical grid line. 
As the grid lines are infinitely thin, a point is infinitely small. Of 
course there are more points on this grid than there are dots on the 
Macintosh screen: when using QuickDraw you associate small parts of 
the grid with areas on the screen, so that you aren't bound into an 
arbitrary, limited coordinate system. 

The coordinate origin (0,0) is in the middle of the grid. Horizontal 
coordinates increase as you move from left to right, and vertical 
coordinates increase as you move from top to bottom. This is the way 
both a TV screen and a page of English text are scanned: from the top 
left to the bottom right. 

You can store the coordinates of a point into a Pascal variable whose 
type is defined by QuickDraw. The type Point is a record of two 
integers, and has this structure: 

TYPE VHSelect = (V,H); 

Point = RECORD CASE INTEGER OF 

0: (v: INTEGER; 

h : INTEGER) ; 

1: (vh: ARRAY [VHSelect] OF INTEGER) 


END; 

The variant part allows you to access the vertical and horizontal 
components of a point either individually or as an array. For example, 
if the variable goodPt were declared to be of type Point, the following 
would all refer to the coordinate parts of the point: 
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goodPt . v 
goodPt .vh[V] 


goodPt .h 
goodPt . vh[H] 


Rectangles 


Any two points can define the top left and bottom right corners of a 
rectangle. As these points are infinitely small, the borders of the 
rectangle are infinitely thin (see Figure 3). 



Bottom. 



Figure 3. A Rectangle 

Rectangles are used to define active areas on the screen, to assign 
coordinate systems to graphic entities, and to specify the locations 
and sizes for various drawing commands. QuickDraw also allows you to 
perform many mathematical calculations on rectangles — changing their 
sizes, shifting them around, and so on. 

( hand) 

Remember that rectangles, like points, are mathematical 
concepts that have no direct representation on the 
screen. The association between these conceptual 
elements and their physical representations is made by a 
bitMap, described below. 

The data type for rectangles is called Rect, and consists of four 
integers or two points: 
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TYPE Rect = RECORD CASE INTEGER OF 


0: (top: INTEGER; 

left: INTEGER; 

bottom: INTEGER; 

right: INTEGER); 


1: (topLeft: Point; 

botRight: Point) 

END; 


Again, the record variant allows you to access a variable of type Rect 
either as four boundary coordinates or as two diagonally opposing 
corner points. Combined with the record variant for points, all of the 
following references to the rectangle named bRect are legal: 


bRect 


bRect . topLef t bRect . 

bRect. top bRect. 
bRect . topLef t . v bRect . 
bRect . topLef t . vh [ V ] bRect • 

bRect . bottom bRect . 
bRect . botRight . v bRect . 
bRect .botRight .vh[V] bRect. 


botRight 

{type 

{type 

Rect } 

Point} 

left 

{type 

INTEGER} 

topLef t.h 

{type 

INTEGER} 

topLef t.vh[H] 

{type 

INTEGER} 

right 

{type 

INTEGER} 

botRight .h 

{type 

INTEGER} 

botRight . vh[H] 

{type 

INTEGER} 


( eye) 

If the bottom coordinate of a rectangle is equal to or 
less than the top, or the right coordinate is equal to or 
less than the left, the rectangle is an empty rectangle 
(i.e., one that contains no bits). 


Regions 

Unlike most graphics packages that can manipulate only simple geometric 
structures (usually rectilinear, at that), QuickDraw has the unique and 
amazing ability to gather an arbitrary set of spatially coherent points 
into a structure called a region, and perform complex yet rapid 
manipulations and calculations on such structures. This remarkable 
feature not only will make your standard programs simpler and faster, 
but will let you perform operations that would otherwise be nearly 
impossible; it is fundamental to the Macintosh user interface. 

You define a region by drawing lines, shapes such as rectangles and 
ovals, or even other regions. The outline of a region should be one or 
more closed loops. A region can be concave or convex, can consist of 
one area or many disjoint areas, and can even have "holes” in the 
middle. In Figure 4, the region on the left has a hole in the middle, 
and the region on the right consists of two disjoint areas. 
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Figure 4. Regions 

Because a region can be any arbitrary area or set of areas on the 
coordinate plane, it takes a variable amount of information to store 
the outline of a region. The data structure for a region, therefore, 
is a variable-length entity with two fixed fields at the beginning, 
followed by a variable-length data field: 

TYPE Region = RECORD 

rgnSize: INTEGER; 

rgnBBox: Rect; 

{optional region definition data} 

END; 

The rgnSize field contains the size, in bytes, of the region variable. 
The rgnBBox field is a rectangle which completely encloses the region. 

The simplest region is a rectangle. In this case, the rgnBBox field 
defines the entire region, and there is no optional region data. For 
rectangular regions (or empty regions), the rgnSize field contains 10. 

The region definition data for nonrectangular regions is stored in a 
compact way which allows for highly efficient access by QuickDraw 
procedures . 

As regions are of variable size, they are stored dynamically on the 
heap, and the Operating System^s memory management moves them around as 
their sizes change. Being dynamic, a region can be accessed only 
through a pointer; but when a region is moved, all pointers referring 
to it must be updated. For this reason, all regions are accessed 
through handles , which point to one master pointer which in turn points 
to the region. 

TYPE RgnPtr = "Region; 

RgnHandle = "RgnPtr; 
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When the memory management relocates a region's data In memory, it 
updates only the RgnPtr master pointer to that region. The references 
through the master pointer can find the region's new home, but any 
references pointing directly to the region's previous position in 
memory would now point at dead bits. To access individual fields of a 
region, use the region handle and double indirection: 

myRgn^.rgnSize {size of region whose handle is myRgn} 

myRgn ^'.rgnBBox {rectangle enclosing the same region} 

myRgn — .rgnBBox.top {minimum vertical coordinate of all 

points in the region} 


myRgn " . rgnBBox 


{syntactically incorrect; will not compile 
if myRgn is a rgnHandle} 


Regions are created by a QuickDraw function which allocates space for 
the region, creates a master pointer, and returns a rgnHandle. When 
you're done with a region, you dispose of it with another QuickDraw 
routine which frees up the space used by the region. Only these calls 
allocate or deallocate regions; do NOT use the Pascal procedure NEW to 
create a new region! 

You specify the outline of a region with procedures that draw lines and 
shapes, as described in the section "QuickDraw Routines . An example 
is given in the discussion of CloseRgn under "Calculations with 
Regions" in that section. 

Many calculations can be performed on regions. A region can be 
"expanded" or "shrunk" and, given any two regions, QuickDraw can find 
their union, intersection, difference, and exclusive-OR ; it can also 
determine whether a given point or rectangle intersects a given region, 
and so on. There is of course a set of graphic operations on regions 
to draw them on the screen. 


GRAPHIC ENTITIES 

Coordinate planes, points, rectangles, and regions are all good 
mathematical models, but they aren't really graphic elements — they 
don't have a direct physical appearance. Some graphic entities that do 
have a direct graphic interpretation are the bit image , bitMap , 
pattern, and cursor. This section describes the data structure of 
these graphic, entities and how they relate to the mathematical 
constructs described above. 
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The Bit Image 

A bit image is a collection of bits in memory which have a rectilinear 
representation. Take a collection of words in memory and lay them end 
to end so that bit 15 of the lowest-numbered word is on the left and 
bit 0 of the highest-numbered word is on the far right. Then take this 
array of bits and divide it, on word boundaries, into a number of 
equal-size rows. Stack these rows vertically so that the first row is 
on the top and the last row is on the bottom. The result is a matrix 

like the one shown in Figure 5 — rows and columns of bits, with each 

row containing the same number of bytes. The number of bytes in each 

row of the bit image is called the row width of that image. 


First 



Figure 5. A Bit Image 


A bit image can be stored in any static or dynamic variable, and can be 
of any length that is a multiple of the row width. 

The Macintosh screen itself is one large visible bit image. The upper 
21,888 bytes of memory are displayed as a matrix of 175,104 pixels on 
the screen, each bit corresponding to one pixel. If a bit's value is 
0, its pixel is white; if the bit's value is 1, the pixel is black. 

The screen is 342 pixels tall and 512 pixels wide, and the row width of 
its bit image is 64 bytes. Each pixel on the screen is square; there 
are 72 pixels per inch in each direction. 

( hand ) 

Since each pixel on the screen represents one bit in a 
bit image, wherever this document says "bit”, you can 
substitute "pixel" if the bit image is the Macintosh 
screen. Likewise, this document often refers to pixels 
on the screen where the discussion applies equally to 
bits in an off-screen bit image. 
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The BitMap 


When you combine the physical entity of a bit image with the conceptual 
entities of the coordinate plane and rectangle, you get a bitMap. A 
bitMap has three parts: a pointer to a bit image, the row width (in 
bytes) of that image, and a boundary rectangle which gives the bitMap 
both its dimensions and a coordinate system. Notice that a bitMap does 
not actually include the bits themselves: it points to them. 

There can be several bitMaps pointing to the same bit image, each 
imposing a different coordinate system on it. This important feature 
is explained more fully in "Coordinates in GrafPorts" , below. 

As shown in Figure 6, the data structure of a bitMap is as follows: 

TYPE BitMap = RECORD 

baseAddr: QDPtr; 

rowBytes: INTEGER; 
bounds: Rect 

END; 



Figure 6. A BitMap 

The baseAddr field is a pointer to the beginning of the bit image in 
memory, and the rowBytes field is the number of bytes in each row of 
the image. Both of these should always be even: a bitMap should 
always begin on a word boundary and contain an integral number of words 
in each row. 

The bounds field is a boundary rectangle that both encloses the active 
area of the bit image and imposes a coordinate system on it. The 
relationship between the boundary rectangle and the bit image in a 
bitMap is simple yet very important. First, a few general rules: 
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- Bits in a bit image fall between points on the coordinate plane. 

- A rectangle divides a bit image into two sets of bits: those bits 
inside the rectangle and those outside the rectangle. 

- A rectangle that is H points wide and V points tall encloses 
exactly (H-1)*(V-1) bits. 

The ton left corner of the boundary rectangle is aligned around the 
f^Ut In Jhe bit image. The width of the rectangle eterminee how 
many bits of one row are logically owned by the bitHap, the 
relationship 

8*map.rowBytes >= map. bounds. right-map. bounds. left 

must always be true. The height of the rectangle determines how many 
rows of the image are logically owned by the bitMap; the relationship 

SIZE0F(map.baseAddO >= (map. bounds. bottom-map. bounds. top) 

* map.rowBytes 

must always be true to ensure that the number of bits in the logical 
bitMap area is not larger than the number of bits in the bit imag . 

Normally, the boundary rectangle completely encloses the blt i “®®’ 

the width of the boundary rectangle is equal to the number o 

one row of the image, and the height of the rectangle is equal to the 

number of rows in the image. If the rectangle is smaller than the 

dimensions of the image, the least signif: leant bi ts in* each 

well as the last rows in the image, are not affected by any operatio 

on the bitMap. 

The bitMap also imposes a coordinate system on the image. Because bits 

fall between coordinate points, the coordinate system assigns integer 

values to the lines that border and separate bits, not to the bi 

positions themselves. For example, if a bitMap is 

boundary rectangle with corners (10,-8) and ( , ), ® ° 

bit in the image will be between horizontal coordinates 33 and 34, 

between vertical coordinates 7 and 8 (see Figure 7). 
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Figure 7. Coordinates and BitMaps 


Patterns 


A pattern is a 64-bit image, organized as an 8-by-8-bit square, which 
is used to define a repeating design (such as stripes) or tone (such as 
gray). Patterns can be used to draw lines and shapes or to fill areas 
on the screen. 

When a pattern is drawn, it is aligned such that adjacent areas of the 
same pattern in the same graphics port will blend with it into a 
continuous, coordinated pattern. QuickDraw provides the predefined 
patterns white, black, gray, ltGray, and dkGray. Any other 64-bit 
variable or constant can be used as a pattern, too. The data type 
definition for a pattern is as follows: 

TYPE Pattern = PACKED ARRAY [0. .7 ] OF 0. .255; 

The row width of a pattern is 1 byte. 


Cursors 


A cursor is a small image that appears on the screen and is controlled 
by the mouse. (It appears only on the screen, and never in an 
off-screen bit image.) 

( hand) 

Other Macintosh documentation calls this image a 
"pointer ", since it points to a location on the screen. 

To avoid confusion with other meanings of "pointer” in 
this manual and other Toolbox documentation, we use the 
alternate term "cursor". 
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A cursor is defined as a 256-bit image, a 16-by-16-bit square. The row 
width of a cursor is 2 bytes. Figure 8 illustrates four cursors. 



Figure 8. Cursors 


A cursor has three fields: a 16— word data field that contains the 
image itself, a 16-word mask field that contains information about the 
screen appearance of each bit of the cursor, and a hotSpot point that 
aligns the cursor with the position of the mouse. 


TYPE Cursor = RECORD 

data: ARRAY [0. .15] OF INTEGER; 

mask: ARRAY [0. .15] OF INTEGER; 

hotSpot: Point 

END; 

The data for the cursor must begin on a word boundary. 

The cursor appears on the screen as a 16-by-16-bit square. The 
appearance of each bit of the square is determined by the corresponding 
bits in the data and mask and, if the mask bit is 0, by the pixel 
"under" the cursor (the one already on the screen in the same position 
as this bit of the cursor): 


Data 

T~ 

i 

0 

1 


Mask Res ulting pixel on screen 
1 White 

1 Black 

0 Same as pixel under cursor 

0 Inverse of pixel under cursor 


Notice that if all mask bits are 0, the cursor is completely 
transparent, in that the image under the cursor can still be viewed: 
pixels under the white part of the cursor appear unchanged, while under 
the black part of the cursor, black pixels show through as white. 
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The hotSpot aligns a point in the image (not a bit, a point!) with the 
mouse position. Imagine the rectangle with corners ( 0 , 0 ) and (16,16) 
framing the image, as in each of the examples in Figure 8; the hotSpot 
is defined in this coordinate system. A hotSpot of ( 0 , 0 ) is at the top 

left of the image. For the arrow in Figure 8 to point to the mouse 

position, ( 0 , 0 ) would be its hotSpot. A hotSpot of (8,8) is in the 

exact center of the image; the center of the plus sign or circle in 

Figure 8 would coincide with the mouse position if (8,8) were the 
hotSpot for that cursor. Similarly, the hotSpot for the pointing hand 
would be (16,9). 

Whenever you move the mouse , the low-level interrupt-driven mouse 
routines move the cursors hotSpot to be aligned with the new mouse 
position. 

( hand) 

The mouse position is always linked to the cursor 
position. You can't reposition the cursor through 
software; the only control you have is whether it's 
visible or not, and what shape it will assume. Think of 
it as being hard-wired: if the cursor is visible, it 
always follows the mouse over the full size of the 
screen. 

QuickDraw supplies a predefined arrow cursor, an arrow pointing 
north-northwest . 


THE DRAWING ENVIRONMENT : GRAFPORT 

A grafPort is a complete drawing environment that defines how and where 
graphic operations will have their effect. It contains all the 
information about one instance of graphic output that is kept separate 
from all other instances. You can have many grafPorts open at once, 
and each one will have its own coordinate system, drawing pattern, 
background pattern, pen size and location, character font and style, 
and bitMap in which drawing takes place. You can instantly switch from 
one port to another. GrafPorts are the structures on which a program 
builds windows, which are fundamental to the Macintosh "overlapping 
windows" user interface. 
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A grafPort is a dynamic data structure, defined as follows 


TYPE GrafPtr 
GrafPort 


"GrafPort ; 

RECORD 
device: 
portBits : 
portRect : 
vi sRgn : 
clipRgn: 
bkPat : 
fillPat: 
pnLoc: 
pnSize: 
pnMode : 
pnPat: 
pnVis : 
txFont: 
txFace: 
txMode : 
txSize: 
spExtra: 
fgColor: 
bkColor: 
colrBit: 
patStretch: 
picSave: 
rgnSave : 
poly Save : 
grafProcs : 

END; 


INTEGER; 
BitMap ; 

Rect ; 

RgnHandle ; 

RgnHand le ; 

Pattern; 

Pattern; 

Point; 

Point; 

INTEGER ; 

Pattern; 

INTEGER; 

INTEGER; 

Style; 

INTEGER; 

INTEGER; 

INTEGER; 

Longlnt ; 

Longlnt ; 

INTEGER ; 

INTEGER; 

QDHandle; 

QDHandle ; 

QDHandle ; 

QDProcsPtr 


All QuickDraw operations refer to grafPorts via graf • in 

grafPort with the Pascal procedure NEW and use the rea “^ 8 P f 

calls to QuickDraw. You could, of course, declare a static VAR yp 
grafPort, and obtain a pointer to that static structure (with the @ 
operator), but as most grafPorts will be used dynamically, their data 
structures should be dynamic also. 


You can access all fields and subfields of a grafPort 
normally, but you should not store new values directly 
into them. QuickDraw has procedures for altering a 
fields of a grafPort, and using these procedures ensures 
that changing a grafPort produces no unusual side 
effects. 


The device field of a grafPort is the number of the logical output 
device that the grafPort will be using. The Font ^ 

information, since there are physical differences in the same logical 
font for different output devices. The default de vice number is 0, for 
the Macintosh screen. For more information about device numbers, see 
the *** not yet existing *** Font Manager documentation. 
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The portBits field is the bitMap that points to the bit image to be 
used by the grafPort. All drawing that is done in this grafPort will 
take place in this bit image. The default bitMap uses the entire 
Macintosh screen as its bit image, with rowBytes of 64 and a boundary 
rectangle of (0,0,512,342). The bitMap may be changed to indicate a 
different structure in memory: all graphics procedures work in exactly 
the same way regardless of whether their effects are visible on the 
screen. A program can, for example, prepare an image to be printed on 
a printer without ever displaying the image on the screen, or develop a 
picture in an off-screen bitMap before transferring it to the screen. 

By altering the coordinates of the portBits. bounds rectangle, you can 
change the coordinate system of the grafPort; with a QuickDraw 
procedure call, you can set an arbitrary coordinate system for each 
grafPort, even if the different grafPort s all use the same bit image 
(e.g., the full screen). 

The portRect field is a rectangle that defines a subset of the bitMap 
for use by the grafPort. Its coordinates are in the system defined by 
the portBits. bounds rectangle. All drawing done by the application 
occurs inside this rectangle. The portRect usually defines the 
"writable" interior area of a window, document, or other object on the 
screen. 

The visRgn field is manipulated by the Window Manager; users and 
programmers will normally never change a grafPort 's visRgn. It 
indicates that region (remember, an arbitrary area or set of areas) 
which is actually visible on the screen. For example, if you move one 
window in front of another, the Window Manager logically removes the 
area of overlap from the visRgn of the window in the back. When you 
draw into the back window, whatever^s being drawn is clipped to the 
visRgn so that it doesn^t run over onto the front window. The default 
visRgn is set to the portRect. The visRgn has no effect on images that 
are not displayed on the screen. 

The clipRgn is an arbitrary region that the application can use to 
limit drawing to any region within the portRect. If, for example, you 
want to draw a half circle on the screen, you can set the clipRgn to 
half the square that would enclose the whole circle, and go ahead and 
draw the whole circle. Only the half within the clipRgn will actually 
be drawn in the grafPort. The default clipRgn is set arbitrarily 
large, and you have full control over its setting. Notice that unlike 
the visRgn, the clipRgn affects the image even if it is not displayed 
on the screen. 

Figure 9 illustrates a typical bitMap (as defined by portBits), 
portRect, visRgn, and clipRgn. 
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Figure 9. Graf Port Regions 


The bkPat and fillPat fields of a grafPort contain patterns used by 
certain QuickDraw routines. BkPat is the "background" pattern that is 
used when an area is erased or when bits are scrolled out of it. When 
asked to fill an area with a specified pattern, QuickDraw stores the 
given pattern in the fillPat field and then calls a low-level drawing 
routine which gets the pattern from that field. The various graphic 
operations are discussed in detail later in the descriptions of 
individual QuickDraw routines. 

Of the next ten fields, the first five determine characteristics of the 
graphics pen and the last five determine characteristics of any text 
that may be drawn; these are described in subsections below. 

The fgColor, bkColor, and colrBit fields contain values related to 
drawing in color, a capability that will be available in the future 
when Apple supports color output devices for the Macintosh. FgColor is 
the graf Port's foreground color and bkColor is its background color. 
ColrBit tells the color imaging software which plane of the color 
picture to draw into. For more information, see "Drawing in Color" in 
the general discussion of drawing. 

The patStretch field is used during output to a printer to expand 
patterns if necessary. The application should not change its value. 

The picSave, rgnSave, and polySave fields reflect the state of picture, 
region, and polygon defintion, respectively. To define a region, for 
example, you "open" it, call routines that draw it, and then "close" 
it. If no region is open, rgnSave contains NIL; otherwise, it contains 
a handle to information related to the region definition. The 
application should not be concerned about exactly what information the 
handle leads to; you may, however, save the current value of rgnSave, 
set the field to NIL to disable the region definition, and later 
restore it to the saved value to resume the region definition. The 
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picSave and polySave fields work similarly for pictures and polygons. 

Finally, the grafProcs field may point to a special data structure that 
the application stores into if it wants to customize QuickDraw drawing 
procedures or use QuickDraw in other advanced, highly specialized ways. 
(For more information, see "Customizing QuickDraw Operations".) If 
grafProcs is NIL, QuickDraw responds in the standard ways described in 
this manual. 


Pen Characteristics 


The pnLoc, pnSize, pnMode, pnPat, and pnVis fields of a grafPort deal 
with the graphics pen. Each grafPort has one and only one graphics 
pen, which is used for drawing lines, shapes, and text. As illustrated 
in Figure 10, the pen has four characteristics: a location, a size, a 
drawing mode, and a drawing pattern. 
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Figure 10. A Graphics Pen 

The pen location is a point in the coordinate system of the grafPort, 
and is where QuickDraw will begin drawing the next line, shape, or 
character. It can be anywhere on the coordinate plane: there are no 
restrictions on the movement or placement of the pen. Remember that 
the pen location is a point on the coordinate plane, not a pixel in a 
bit image! 

The pen is rectangular in shape, and has a user-definable width and 
height. The default size is a 1-by-l-bit square; the width and height 
can range from (0,0) to (32767,32767). If either the pen width or the 
pen height is less than 1, the pen will not draw on the screen. 

- The pen appears as a rectangle with its top left corner at the pen 
location; it hangs below and to the right of the pen location. 
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The pnMode and pnPat fields of a grafPort determine how the bits under 
the pen are affected when lines or shapes are drawn. The pnPat is a 
pattern that is used like the "ink" in the pen. This pattern, like all 
other patterns drawn in the grafPort, is always aligned with the port s 
coordinate system: the top left corner of the pattern is aligned with 
the top left corner of the portRect, so that adjacent areas of the same 
pattern will blend into a continuous, coordinated pattern. Five 
patterns are predefined (white, black, and three shades of gray); you 
can also create your own pattern and use it as the pnPat. (A utility 
procedure, called StuffHex, allows you to fill patterns easily.) 

The pnMode field determines how the pen pattern is to affect what s 
already on the bitMap when lines or shapes are drawn. When the pen 
draws, QuickDraw first determines what bits of the bitMap will be 
affected and finds their corresponding bits in the pattern. It then 
does a bit-by-bit evaluation based on the pen mode, which specifies one 
of eight boolean operations to perform. The resulting bit is placed 
into its proper place In the bitMap. The pen modes are described under 
"Transfer Modes" in the general discussion of drawing below. 

The pnVis field determines the pen's visibility, that is, whether it 
draws on the screen. For more information, see the descriptions of 
HidePen and ShowPen under "Pen and Line-Drawing Routines" in the 
"QuickDraw Routines" section. 


Text Characteristics _ 

The txFont , txFace, txMode, txSize, and spExtra fields of a grafPort 
determine how text will be drawn — the font, style, and size of 
characters and how they will be placed on the bitMap. 

( hand ) 

In the Macintosh User Interface Toolbox, character style 
means stylistic variations such as bold, italic, and 
underline; font means the complete set of characters of 
one typeface, such as Helvetica, and does not include the 
character style or size. 

QuickDraw can draw characters as quickly and easily as it draws lines 
and shapes, and in many prepared fonts. Figure 11 shows two QuickDraw 
characters and some terms you should become familiar with. 
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Figure 11. QuickDraw Characters 

QuckDraw can display characters in any size, as well as boldfaced, 
italicized, outlined, or shadowed, all without changing fonts. It can 
also underline the characters, or draw them closer together or farther 
apart . 

The txFont field is a font number that identifies the character font to 
be used in the grafPort. The font number 0 represents the system font. 
For more information about the system font, the other font numbers 
recognized by the Font Manager, and the construction, layout, and 
loading of fonts, see the *** not yet existing *** Font Manager 
documentation. 

A character font is defined as a collection of bit images: these 
images make up the individual characters of the font. The characters 
can be of unequal widths, and they ^ re not restricted to their "cells”: 
the lower curl of a lowercase j, for example, can stretch back under 
the previous character (typographers call this kerning ). A font can 
consist of up to 256 distinct characters, yet not all characters need 
be defined in a single font. Each font contains a missing symbol to be 
drawn in case of a request to draw a character that is missing from the 
font. 

The txFace field controls the appearance of the font with values from 
the set defined by the Style data type: 

TYPE Styleltem = (bold, italic, underline, outline, shadow, 
condense, extend); 

Style = SET OF Styleltem; 

You can apply these either alone or in combination (see Figure 12). 

Most combinations usually look good only for large fonts. 
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Normal Characters 
Bold Characters 

M Cda/aciers 
Underlined Charact ers xyz 

MStimtfl OtenseSire 

©SafrasSura 
Condensed Characters 
E xt e n d e d C h ar act e r s 
Bold italic Characters 
MHl (BwiffliiTsril lUhiferiftwafl 

. . . and in other fonts, tool 

Figure 12. Character Styles 

If you specify bold, each character is repeatedly drawn one bit to the 
right an appropriate number of times for extra thickness. 

Italic adds an italic slant to the characters. Character bits above 
the base line are skewed right; bits below the base line are skewed 
left. 

Underline draws a line below the base line of the characters. If part 
of a character descends below the base line (as y in Figure 12), the 
underline is not drawn through the pixel on either side of the 
descending part. 

You may specify either outline or shadow. Outline makes a hollow, 
outlined character rather than a solid one. With shadow, not only is 
the character hollow and outlined, but the outline is thickened below 
and to the right of the character to achieve the effect of a shadow. 

If you specify bold along with outline or shadow, the hollow part of 
the character is widened. 

Condense and extend affect the horizontal distance between all 
characters, including spaces. Condense decreases the distance between 
characters and extend increases it, by an amount which the Font Manager 
determines is appropriate. 

The txMode field controls the way characters are placed on a bit image. 
It functions much like a pnModet when a character is drawn, QuickDraw 
determines which bits of the bit image will be affected, does a 
bit-by-bit comparison based on the mode, and stores the resulting bits 
into the bit image. These modes are described under Transfer Modes 
in the general discussion of drawing below. Only three of them 
srcOr, srcXor, and srcBic — should be used for drawing text. 
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The txSize field specifies the type size for the font, in points (where 
"point" here is a printing term meaning 1/72 inch). Any size may be 
specified. If the Font Manager does not have the font in a specified 
size, it will scale a size it does have as necessary to produce the 
size desired. A value of 0 in this field directs the Font Manager to 
choose the size from among those it has for the font; it will choose 
whichever size is closest to the system font size. 

Finally, the spExtra field is useful when a line of characters is to be 
drawn justified such that it is aligned with both a left and a right 
margin (sometimes called "full justification"). SpExtra is the number 
of pixels by which each space character should be widened to fill out 
the line. 


COORDINATES IN GRAF PORTS 


Each grar'Port has its own local coordinate system. All fields in the 
grafPort are expressed in these coordinates, and all calculations and 
actions performed in QuickDraw use the local coordinate system of the 
currently selected port. 

Two things are important to remember: 

- Each grafPort maps a portion of the coordinate plane into a 
similarly-sized portion of a bit image. 

- The portBits. bounds rectangle defines the local coordinates for a 
grafPort . 

The top left corner of portBits. bounds is always aligned around the 
first bit in the bit image; the coordinates of that corner "anchor” a 
point on the grid to that bit in the bit image. This forms a common 
reference point for multiple grafPorts using the same bit image (such 
as the screen). Given a portBits. bounds rectangle for each port, you 
know that their top left corners coincide. 

The interrelationship between the portBits. bounds and portRect 
rectangles is very important. As the portBits. bounds rectangle 
establishes a coordinate system for the port, the portRect rectangle 
indicates the section of the coordinate plane (and thus the bit image) 
that will be used for drawing. The portRect usually falls inside the 
portBits. bounds rectangle, but it's not required to do so. 

When a new grafPort is created, its bitMap is set to point to the 
entire Macintosh screen, and both the portBits. bounds and the portRect 
rectangles are set to 512-by-342-bit rectangles, with the point (0,0) 
at the top left corner of the screen. 

You can redefine the local coordinates of the top left corner of the 
8 r 3fPort s portRect, using the SetOrigin procedure. This changes the 
local coordinate system of the grafPort, recalculating the coordinates 
all points in the grafPort to be relative to the new corner 


3/2/83 Espinosa-Rose 


CONFIDENTIAL 


/QUICK/QUIKDRAW . 3 



26 


QuickDraw Programmers Guide 


coordinates. For example, consider these procedure calls: 

SetPort (gamePort ) ; 

SetOrigin(40,80) ; 

The call to SetPort sets the current grafPort to gamePort; the call to 
SetOrigin changes the local coordinates of the top left corner of that 
port^s portRect to (40,80) (see Figure 13). 


0 95 300 512 -55 40 245 457 



Figure 13. Changing Local Coordinates 
This recalculates the coordinate components of the following elements: 
gamePort"' . port Bits . bounds gamePort portRect 

gamePort ~ . visRgn 

These elements are always kept "in sync", so that all calculations, 
comparisons, or operations that seem right, work right. 

Notice that when the local coordinates of a grafPort are offset, the 
visRgn of that port is offset also, but the clipRgn is not. A good way 
to think of it is that if a document is being shown inside a grafPort, 
the document "sticks" to the coordinate system, and the port^s 
structure "sticks" to the screen. Suppose, for example, that the 
visRgn and clipRgn in Figure 13 before SetOrigin are the same as the 
portRect, and a document is being shown. After the SetOrigin call, the 
top left corner of the clipRgn is still (95,120), but this location has 
moved down and to the right, and the location of the pen within the 
document has similarly moved. The locations of portBits. bounds, 
portRect, and visRgn did not change; their coordinates were offset. As 
always, the top left corner of portBits. bounds remains aligned around 
the first bit in the bit image (the first pixel on the screen). 

If you are moving, comparing, or otherwise dealing with mathematical 
items in different grafPorts (for example, finding the intersection of 
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two regions in two different grafPorts), you must adjust to a common 
coordinate system before you perform the operation. A QuickDraw 
procedure, LocalToGlobal , lets you convert a point^s local coordinates 
to a global system where the top left corner of the bit image is (0,0); 
by converting the various local coordinates to global coordinates, you 
can compare and mix them with confidence. For more information, see 
the description of this procedure under "Calculations with Points” in 
the section "QuickDraw Routines". 


GENERAL DISCUSSION OF DRAWING 


Drawing occurs : 

- Always inside a grafPort, in the bit image and coordinate system 
defined by the grafPort 's bitMap. 

- Always within the intersection of the graf Port^s portBits. bounds 
and portRect, and clipped to its visRgn and clipRgn. 

- Always at the grafPort^s pen location. 

- Usually with the grafPort 's pen size, pattern, and mode. 

With QuickDraw procedures, you can draw lines, shapes, and text. 
Shapes include rectangles, ovals, rounded-corner rectangles, 
wedge-shaped sections of ovals, regions, and polygons. 

Lines are defined by two points: the current pen location and a 
destination location. When drawing a line, QuickDraw moves the top 
left corner of the pen along the mathematical trajectory from the 
current location to the destination. The pen hangs below and to the 
right of the trajectory (see Figure 14). 



Figure 14. Drawing Lines 
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No mathematical element (such as the pen location) is 
ever affected by clipping; clipping only determines what 
appears where in the bit image. If you draw a line to a 
location outside your grafPort, the pen location will 
move there, but only the portion of the line that is 
inside the port will actually be drawn. This is true for 
all drawing procedures. 

Rectangles, ovals, and rounded-corner rectangles are defined by two 
corner points. The shapes always appear inside the mathematical 
rectangle defined by the two points. A region is defined in a more 
complex manner, but also appears only within the rectangle enclosing 
it. Remember, these enclosing rectangles have infinitely thin borders 

and are not visible on the screen. 

As illustrated in Figure 15, shapes may be drawn either solid (filled 
in with a pattern) or framed (outlined and hollow). 
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Figure 15. Solid Shapes and Framed Shapes 

In the case of framed shapes, the outline appears completely within the 
enclosing rectangle — with one exception and the vertical and 
horizontal thickness of the outline is determined by the pen size. The 
exception is polygons, as discussed in "Pictures and Polygons below. 

The pen pattern is used to fill in the bits that are affected by the 
drawing operation. The pen mode defines how those bits are to be 
affected by directing QuickDraw to apply one of eight boolean 
operations to the bits in the shape and the corresponding pixels on the 
screen. 

Text drawing does not use the pnSize, pnPat, or pnMode, but it does use 
the pnLoc. Each character is placed to the right of the current pen 
location, with the left end of its base line at the pen's location. 

The pen is moved to the right to the location where it will draw the 
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next character. No wrap or carriage return is performed automatically. 

The method QuickDraw uses in placing text is controlled by a mode 
similar to the pen mode. This is explained in "Transfer Modes", below. 
Clipping of text is performed in exactly the same manner as all other 
clipping in QuickDraw. 


Transfer Modes 


When lines or shapes are drawn, the pnMode field of the grafPort 
determines how the drawing is to appear in the port^s bit image; 
similarly, the txMode field determines how text is to appear. There is 
also a QuickDraw procedure that transfers a bit image from one bitMap 
to another, and this procedure has a mode parameter that determines the 
appearance of the result. In all these cases, the mode, called a 
transfer mode, specifies one of eight boolean operations: for each bit 
in the item to be drawn, QuickDraw finds the corresponding bit in the 
destination bit image, performs the boolean operation on the pair of 
bits, and stores the resulting bit into the bit image. 

There are two types of transfer mode: 

- Pattern transfer modes , for drawing lines or shapes with a 
pattern. 

- Source transfer modes , for drawing text or transferring any bit 
image between two bitMap s. 

For each type of mode, there are four basic operations — Copy, Or, 

Xor, and Bic. The Copy operation simply replaces the pixels in the 
destination with the pixels in the pattern or source, "painting" over 
the destination without regard for what is already there. The Or, Xor, 
and Bic operations leave the destination pixels under the white part of 
the pattern or source unchanged, and differ in how they affect the 
pixels under the black part: Or replaces those pixels with black 
pixels, thus "overlaying" the destination with the black part of the 
pattern or source; Xor inverts the pixels under the black part; and Bic 
erases them to white. 

Each of the basic operations has a variant in which every pixel in the 
pattern or source is inverted before the operation is performed, giving 
eight operations in all. Each mode is defined by name as a constant in 
QuickDraw (see Figure 16). 
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pattern or source 
"Y-riATit" " Overlay" 



destination 
"Invert" “Erasa“ 



patCopy 

stcCopy 



patOr 

srcOr 
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srcXor srcBic 



nolPatCopy notP&tOt notPatXot 
notSrcCopy notSrcOr notSrcXor 
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Figure 16. Transfer Modes 
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Drawing in Color 






Currently you can only look at QuickDraw output on a black and-white 
screen or printer. Eventually, however, Apple will support color 
output devices. If you want to set up your application now to P ro ^ u ^ e 
color output in the future, you can do so by using QuickDraw procedures 
to set the foreground color and the background color. Eight standard 
colors may be specified with the following predefined constants: 
blackColor , whiteColor, redColor, greenColor, blueColor, cyanColor, 
magentaColor , and yellowColor. Initially, the foreground color is 
blackColor and the background color is whiteColor. If you spec y 
color other than whiteColor, it will appear as black on a 
black-and-white output device. 


To apply the table in the "Transfer Modes" section above to drawing in 
color, make the following translation: where the table shows Force 
black", read "Force foreground color", and where it shows Force 
white", read "Force background color”. When you eventua y rece 


3/2/83 Espinosa-Rose 


CONFIDENTIAL 


/QUICK/QUIKDRAW.3 





GENERAL DISCUSSION OF DRAWING 


31 


color output device, you'll find out the effect of inverting a color on 
it. 


( hand ) 

QuickDraw can support output devices that have up to 32 
bits of color information per pixel. A color picture may 
be thought of, then, as having up to 32 planes. At any 
one time, QuickDraw draws into only one of these planes. 

A QuickDraw routine called by the color— imaging software 
specifies which plane. 


PICTURES AND POLYGONS 


QuickDraw lets you save a sequence of drawing commands and "play them 
back” later with a single procedure call. There are two such 
mechanisms: one for drawing any picture to scale in a destination 
rectangle that you specify, and another for drawing polygons in all the 
ways you can draw other shapes in QuickDraw. 


Pictures 


A picture in QuickDraw is a transcript of calls to routines which draw 
something anything on a bitMap. Pictures make it easy for one 
program to draw something defined in another program, with great 
flexibility and without knowing the details about what's being drawn. 

For each picture you define, you specify a rectangle that surrounds the 
picture; this rectangle is called the picture frame. When you later 
call the procedure that draws the saved picture, you supply a 
destination rectangle, and QuickDraw scales the picture so that its 
frame is completely aligned with the destination rectangle. Thus, the 
picture may be expanded or shrunk to fit its destination rectangle. 

For example, if the picture is a circle inside a square picture frame, 
and the destination rectangle is not square, the picture is drawn as an 
oval . 

Since a picture may include any sequence of drawing commands, its data 
structure is a variable-length entity. It consists of two fixed fields 
followed by a variable-length data field: 

TYPE Picture = RECORD 

picSize: INTEGER; 

picFrame : Rect ; 

{picture definition data} 

END; 

The picSize field contains the size, in bytes, of the picture variable. 
The picFrame field is the picture frame which surrounds the picture and 
gives a frame of reference for scaling when the picture is drawn. The 
rest of the structure contains a compact representation of the drawing 
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commands that define the picture. 

All pictures are accessed through handles, which point to one master 
pointer which in turn points to the picture. 

TYPE PicPtr = "Picture; 

PicHandle = "PicPtr; 

To define a picture, you call a QuickDraw function that returns a 
picHandle and then call the routines that draw the picture. There is a 
procedure to call when you've finished defining the picture, and 
another for when you're done with the picture altogether. 

QuickDraw also allows you to intersperse picture comments in with the 
definition of a picture. These comments, which do not affect the 
picture's appearance, may be used to provide additional information 
about the picture when it's played back. This is especially valuable 
when pictures are transmitted from one application to another. There 
are two standard types of comment which, like parentheses, serve to 
group drawing commands together (such as all the commands that draw a 
particular part of a picture): 

CONST picLParen = 0; 
picRParen = 1 ; 

The application defining the picture can use these standard comments as 
well as comments of its own design. 

To include a comment in the definition of a picture, the application 
calls a QuickDraw procedure that specifies the comment with three 
parameters: the comment kind, which identifies the type of comment; a 

handle to additional data if desired; and the size of the additional 
data, if any. When playing back a picture, QuickDraw passes any 
comments in the picture's definition to a low-level procedure accessed 
indirectly through the grafProcs field of the grafPort (see 
"Customizing QuickDraw Operations" for more information). To process 
comments, the application must include a procedure to do the processing 
and store a pointer to it in the data structure pointed to by the 
grafProcs field. 

( hand) 

The standard low-level procedure for processing picture 
comments simply ignores all comments. 








Polygons 

Polygons are similar to pictures in that you define them by a sequence 
of calls to QuickDraw routines. They are also similar to other shapes 
that QuickDraw knows about, since there is a set of procedures for 
performing graphic operations and calculations on them. 

A polygon is simply any sequence of connected lines (see Figure 17). 

You define a polygon by moving to the starting point of the polygon and 




3/2/83 Rose 


CONFIDENTIAL 


/QUICK/ QUIKDRAW • P 


PICTURES AND POLYGONS 


33 


drawing lines from there to the next point, from that point to the 
next, and so on. 



Figure 17. Polygons 

The data structure for a polygon is a variable-length entity. It 
consists of two fixed fields followed by a variable-length array: 

TYPE Polygon = RECORD 

poly Size : INTEGER ; 

polyBBox: Rect; 

polyPoints: ARRAY [ 0 . . 0 ] OF Point 
END; 

The polySize field contains the size, in bytes, of the polygon 
variable. The polyBBox field is a rectangle which just encloses the 
entire polygon. The polyPoints array expands as necessary to contain 
the points of the polygon — the starting point followed by each 
succesive point to which a line is drawn. 

Like pictures and regions, polygons are accessed through handles. 

TYPE PolyPtr = ^Polygon; 

PolyHandle =* ^PolyPtr; 

To define a polygon, you call a QuickDraw function that returns a 
polyHandle and then form the polygon by calling procedures that draw 
lines. You call a procedure when you've finished defining the polygon, 
and another when you're done with the polygon altogether. 

Just as for other shapes that QuickDraw knows about, there is a set of 
graphic operations on polygons to draw them on the screen. QuickDraw 
draws a polygon by moving to the starting point and then drawing lines 
to the remaining points in succession, just as when the routines were 
called to define the polygon. In this sense it "plays back" those 
routine calls. As a result, polygons are not treated exactly the same 
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as other QuickDraw shapes. For example, the procedure that frames a 
polygon draws outside the actual boundary of the polygon, because 
QuickDraw line-drawing routines draw below and to the right of the pen 
location. The procedures that fill a polygon with a pattern, however, 
stay within the boundary of the polygon; they also add an additional line 
between the ending point and the starting point if those points are not 
the same, to complete the shape. 

There is also a difference in the way QuickDraw scales a polygon and a 
similarly-shaped region if it's being drawn as part of a picture: when 
stretched, a slanted line is drawn more smoothly if it s part of a 
polygon rather than a region. You may find it helpful to keep in mind 
the conceptual difference between polygons and regions: a polygon is 
treated more as a continuous shape, a region more as a set of bits. 


QUICKDRAW ROUTINES 

This section describes all the procedures and functions in QuickDraw, 
their parameters, and their operation. They are presented in their 
Pascal form; for information on using them from assembly language, see 
"Using QuickDraw from Assembly Language". 


GrafPort Routines 


PROCEDURE InitGraf (globalPtr: QDPtr); 

Call InitGraf once and only once at the beginning of your program to 
initialize QuickDraw. It initializes the QuickDraw global variables 
listed below. 


Variable 

Type 

Initial setting 

thePort 

GrafPtr 

NIL 

white 

Pattern 

all-white pattern 

black 

Pattern 

all-black pattern 

gray 

Pattern 

50% gray pattern 

ltGray 

Pattern 

25% gray pattern 

dkGray 

Pattern 

75% gray pattern 

arrow 

Cursor 

pointing arrow cursor 

screenBits 

BitMap 

Macintosh screen, (0,0,512,342) 

randSeed 

Longlnt 

1 


The globalPtr parameter tells QuickDraw where to store its global 
variables, beginning with thePort. From Pascal programs, this 
parameter should always be set to PthePort; assembly- language 
programmers may choose any location, as long as it can accommodate the 
number of bytes specified by GRAFSIZE in GRAFT Y PE S. TEXT (see Using 
QuickDraw from Assembly Language"). 
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( hand ) 

To initialize the cursor, call InitCursor (described 
under "Cursor-Handling Routines" below). 


PROCEDURE OpenPort (gp: GrafPtr); 

OpenPort allocates space for the given grafPort^s visRgn and clipRgn, 
initializes the fields of the grafPort as indicated below, and makes 
the grafPort the current port (see SetPort). You must call OpenPort 
before using any grafPort; first perform a NEW to create a grafPtr and 
then use that grafPtr in the OpenPort call. 


Field 

Type 

Initial setting 

device 

INTEGER 

0 (Macintosh screen) 

portBits 

BitMap 

screenBits (see InitGraf) 

portRect 

Rect 

sc reenB its. bounds (0,0,512,342) 

visRgn 

RgnHandle 

handle to the rectangular region 
(0,0,512,342) 

clipRgn 

RgnHandle 

handle to the rectangular region 
(-30000 , -30000 , 30000 , 30000 ) 

bkPat 

Pattern 

white 

fillPat 

Pattern 

black 

pnLoc 

Point 

(0,0) 

pnSize 

Point 

(1,1) 

pnMode 

INTEGER 

pat Copy 

pnPat 

Pattern 

black 

pnVis 

INTEGER 

0 (visible) 

txFont 

INTEGER 

0 (system font) 

txFace 

Style 

normal 

txMode 

INTEGER 

srcOr 

txSize 

INTEGER 

0 (Font Manager decides) 

spExtra 

INTEGER 

0 

fgColor 

Longlnt 

blackColor 

bkColor 

Longlnt 

whiteColor 

colrBit 

INTEGER 

0 

patStretch 

INTEGER 

0 

picSave 

QDHandle 

NIL 

rgnSave 

QDHandle 

NIL 

polySave 

QDHandle 

NIL 

grafProcs 

QDProcsPtr 

NIL 


PROCEDURE InitPort (gp: GrafPtr); 

Given a pointer to a grafPort that has been opened with OpenPort, 
InitPort reinitializes the fields of the grafPort and makes it the 
current port (if it's not already). 

( hand) 

InitPort does everything OpenPort does except allocate 
space for the visRgn and clipRgn. 


3/2/83 Espinosa-Rose 


CONFIDENTIAL 


/QUICK/QUIKDRAW • 4 



36 


QuickDraw Programmer's Guide 


PROCEDURE ClosePort (gp: GrafPtr); 

ClosePort deallocates the space occupied by the given grafPort s visRgn 
and clipRgn. When you are completely through with a grafPort, call 
this procedure and then dispose of the grafPort (with a DISPOSE of the 
grafPtr). 

( eye) 

If you do not call ClosePort before disposing of the 
grafPort, the memory used by the visRgn and clipRgn will 
be unrecoverable. 

( eye) 

After calling ClosePort, be sure not to use any copies of 
the visRgn or clipRgn handles that you may have made. 


PROCEDURE SetPort (gp: GrafPtr); 

SetPort sets the grafPort indicated by gp to be the current port. The 
global pointer thePort always points to the current port. All 
QuickDraw drawing routines affect the bitMap thePort .portBits and use 
the local coordinate system of thePort'. Note that OpenPort and 
InitPort do a SetPort to the given port. 

( eye) 

Never do a SetPort to a port that has not been opened 
with OpenPort* 

Each port possesses its own pen and text characteristics which remain 
unchanged when the port is not selected as the current port* 


PROCEDURE GetPort (VAR gp: GrafPtr); 

GetPort returns a pointer to the current grafPort. If you have a 
program that draws into more than one grafPort, it^s extremely useful 
to have each procedure save the current grafPort (with GetPort), set 
its own grafPort, do drawing or calculations, and then restore the 
previous grafPort (with SetPort). The pointer to the current grafPort 
is also available through the global pointer thePort, but you may 
prefer to use GetPort for better readability of your program text. For 
example, a procedure could do a GetPort (savePort) before setting its 
own grafPort and a SetPort (savePort) afterwards to restore the previous 
port. 


PROCEDURE Graf Device (device: INTEGER); 

GrafDevice sets thePort ~ .device to the given number, which identifies 
the logical output device for this grafPort. The Font Manager uses 
this information. The initial device number is 0, which represents the 
Macintosh screen. 
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PROCEDURE SetPortBits (bm: BitMap); 

SetPortBits sets thePort*. portBits to any previously defined bitMap. 
This allows you to perform all normal drawing and calculations on a 
buffer other than the Macintosh screen — for example, a 640-by-7 
output^buffer for a C. Itoh printer, or a small off-screen image for 
later "stamping” onto the screen. 

Remember to prepare all fields of the bitMap before you call 
SetPortBits. 


PROCEDURE PortSize (width, height : INTEGER); 

PortSize changes the size of the current grafPort's portRect. THIS 
DOES NOT AFFECT THE SCREEN; it merely changes the size of the "active 
area” of the grafPort. 

( hand ) 

This procedure is normally called only by the Window 
Manager. 

The top left corner of the portRect remains at its same location; the 
width and height of the portRect are set to the given width and height. 
In other words, PortSize moves the bottom right corner of the portRect 
to a position relative to the top left corner. 

PortSize does not change the clipRgn or the visRgn, nor does it affect 
the local coordinate system of the grafPort: it changes only the 
portRect s width and height. Remember that all drawing occurs only in 
the intersection of the portBits. bounds and the portRect, clipped to 
the visRgn and the clipRgn. 


PROCEDURE MovePortTo (leftGlobal.topGlobal: INTEGER); 

MovePortTo changes the position of the current grafPort's portRect. 
THIS DOES NOT AFFECT THE SCREEN; it merely changes the location at 
which subsequent drawing inside the port will appear. 

( hand) 

This procedure is normally called only by the Window 
Manager. 

The lef tGlobal and topGlobal parameters set the distance between the 
top left corner of portBits .bounds and the top left corner of the new 
portRect. For example, 

MovePortTo(256, 171 ) ; 

will move the top left corner of the portRect to the center of the 
screen (if portBits is the Macintosh screen) regardless of the local 
coordinate system. 
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Like PortSize, MovePortTo does not change the clipRgn or the visRgn, 
nor does it affect the local coordinate system of the grafPort. 


PROCEDURE SetOrigin (h,v: INTEGER); 

SetOrigin changes the local coordinate system of the current grafPort# 
THIS DOES NOT AFFECT THE SCREEN; it does, however, affect where 
subsequent drawing and calculation will appear in the grafPort# 
SetOrigin updates the coordinates of the portBits# bounds, the portRect, 
and the visRgn. All subsequent drawing and calculation routines will 
use the new coordinate system. 

The h and v parameters set the coordinates of the top left corner of 
the portRect# All other coordinates are calculated from this point. 

All relative distances among any elements in the port will remain the 
same; only their absolute local coordinates will change. 

( hand) 

SetOrigin does not update the coordinates of the clipRgn 
or the pen; these items stick to the coordinate system 
(unlike the port's structure, which sticks to the 
screen) • 

SetOrigin is useful for adjusting the coordinate system after a 
scrolling operation. (See ScrollRect under 'Bit Transfer Operations 
below. ) 


PROCEDURE SetClip ( rgn : RgnHandle ) ; 

SetClip changes the clipping region of the current grafPort to a region 
equivalent to the given region. Note that this does not change the 
region handle, but affects the clipping region itself. Since SetClip 
makes a copy of the given region, any subsequent changes you make to 
that region will not affect the clipping region of the port. 

You can set the clipping region to any arbitrary region, to aid you in 
drawing inside the grafPort. The initial clipRgn is an arbitrarily 
large rectangle. 


PROCEDURE GetClip (rgn: RgnHandle); 

GetClip changes the given region to a region equivalent to the clipping 
region of the current grafPort. This is the reverse of what SetClip 
does. Like SetClip, it does not change the region handle. 


PROCEDURE ClipRect (r: Rect); 

ClipRect changes the clipping region of the current grafPort to a 
rectangle equivalent to given rectangle. Note that this does not 
change the region handle, but affects the region itself. 
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PROCEDURE BackPat (pat: Pattern); 

BackPat sets the background pattern of the current grafPort to the 
given pat tern • The background pattern is used in ScrollRect and in all 
QuickDraw routines that perform an "erase" operation. 


Cursor-Handling Routines 


PROCEDURE InitCursor; 

InitCursor sets the current cursor to the predefined arrow cursor, an 
arrow pointing north-northwest, and sets the cursor level to 0, making 
the cursor visible. The cursor level, which is initialized to 0 when 
the system is booted, keeps track of the number of times the cursor has 
been hidden to compensate for nested calls to HideCursor and ShowCursor 
(below) . 

Before you call InitCursor, the cursor is undefined (or, if set by a 
previous process, it's whatever that process set it to). 


PROCEDURE SetCursor (crsr: Cursor); 

SetCursor sets the current cursor to the 16-by-16-bit image in crsr. 

If the cursor is hidden, it remains hidden and will attain the new 
appearance when it's uncovered; if the cursor is already visible, it 
changes to the new appearance immediately. 

The cursor image is initialized by InitCursor to a north— northwest 
arrow, visible on the screen. There is no way to retrieve the current 
cursor image. 

PROCEDURE HideCursor; 

HideCursor removes the cursor from the screen, restoring the bits under 
it, and decrements the cursor level (which InitCursor initialized to 
0). Every call to HideCursor should be balanced by a subsequent call 
to ShowCursor. 


PROCEDURE ShowCursor; 

ShowCursor increments the cursor level, which may have been decremented 
by HideCursor, and displays the cursor on the screen if the level 
becomes 0. A call to ShowCursor should balance each previous call to 
HideCursor. The level is not incremented beyond 0, so extra calls to 
ShowCursor don't hurt. 

QuickDraw low-level interrupt-driven routines link the cursor with the 
mouse position, so that if the cursor level is 0 (visible), the cursor 
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automatically follows the mouse* You don't need to do anything but a 
ShowCursor to have a cursor track the mouse. There is no way to 
"disconnect" the cursor from the mouse; you can't force the cursor to a 
certain position, nor can you easily prevent the cursor from entering a 
certain area of the screen* 

If the cursor has been changed (with SetCursor) while hidden, 

ShowCursor presents the new cursor. 

The cursor is initialized by InitCursor to a north-northwest arrow, not 
hidden. 


PROCEDURE ObscureCursor ; 

ObscureCursor hides the cursor until the next time the mouse is moved. 
Unlike HideCursor, it has no effect on the cursor level and must not be 
balanced by a call to ShowCursor. 


Pen and Line-Drawing Routines 

The pen and line-drawing routines all depend on the coordinate system 
of the current grafPort. Remember that each grafPort has its own pen; 
if you draw in one grafPort, change to another, and return to the 
first, the pen will have remained in the same location. 


PROCEDURE HidePen; 

HidePen decrements the current graf Port's pnVis field, which is 
initialized to 0 by OpenPort; whenever pnVis is negative, the pen does 
not draw on the screen. PnVis keeps track of the number of times the 
pen has been hidden to compensate for nested calls to HidePen and 
ShowPen (below). HidePen is called by OpenRgn, OpenPicture, and 
OpenPoly so that you can define regions, pictures, and polygons without 
drawing on the screen. 


PROCEDURE ShowPen; 

ShowPen increments the current graf Port's pnVis field, which may have 
been decremented by HidePen; if pnVis becomes 0, QuickDraw resumes 
drawing on the screen. Extra calls to ShowPen will increment pnVis 
beyond 0, so every call to ShowPen should be balanced by a subsequent 
call to HidePen. ShowPen is called by CloseRgn, ClosePicture, and 
ClosePoly. 


PROCEDURE GetPen (VAR pt : Point); 

GetPen returns the current pen location, in the local coordinates of 
the current grafPort. 
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PROCEDURE GetPenState (VAR pnState: PenState); 

GetPenState saves the pen location, size, pattern, and mode into a 
storage variable, to be restored later with SetPenState (below). This 
is useful when calling short subroutines that operate in the current 
port but must change the graphics pen: each such procedure can save 
the pen's state when it's called, do whatever it needs to do, and 
restore the previous pen state immediately before returning. 

The PenState data type is not useful for anything except saving the 
pen's state. 


PROCEDURE SetPenState (pnState: PenState); 

SetPenState sets the pen location, size, pattern, and mode in the 
current grafPort to the values stored in pnState. This is usually 
called at the end of a procedure that has altered the pen parameters 
and wants to restore them to their state at the beginning of the 
procedure. (See GetPenState, above.) 


PROCEDURE PenSize (width, height : INTEGER); 

PenSize sets the dimensions of the graphics pen in the current 
grafPort. All subsequent calls to Line, LineTo, and the procedures 
that draw framed shapes in the current grafPort will use the new pen 
dimensions. 

The pen dimensions can be accessed in the variable thePort^.pnSize, 
which is of type Point. If either of the pen dimensions is set to a 
negative value, the pen assumes the dimensions (0,0) and no drawing is 
performed. For a discussion of how the pen draws, see the "General 
Discussion of Drawing" earlier in this manual. 


PROCEDURE PenMode (mode: INTEGER); 

PenMode sets the transfer mode through which the pnPat is transferred 
onto the bitMap when lines or shapes are drawn. The mode may be any 
one of the pattern transfer modes: 

patCopy patXor notPatCopy notPatXor 

patOr patBic notPatOr notPatBic 

If the mode is one of the source transfer modes (or negative), no 
drawing is performed. The current pen mode can be obtained in the 
variable thePort~.pnMode. The initial pen mode is patCopy, in which 
the pen pattern is copied directly to the bitMap. 
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PROCEDURE PenPat (pat: Pattern); 

PenPat sets the pattern that is used by the pen in the current 
grafPort. The standard patterns white, black, gray, ltGray, and dkGray 
are predefined; the initial pnPat is black. The current pen pattern 
can be obtained in the variable thePort". pnPat, and this value can be 
assigned (but not compared!) to any other variable of type Pattern. 


PROCEDURE PenNormal; 

PenNormal resets the initial state of the pen in the current grafPort, 
as follows: 

Field Setting 

pnSize (1,1) 

pnMode pat Copy 

pnPat black 

The pen location is not changed. 


PROCEDURE MoveTo (h,v: INTEGER); 

MoveTo moves the pen to location (h,v) in the local coordinates of the 
current grafPort. No drawing is performed. 


PROCEDURE Move (dh,dv: INTEGER); 

This procedure moves the pen a distance of dh horizontally and dv 
vertically from its current location; it calls MoveTo (hfdh, v+dv) , where 
(h,v) is the current location. The positive directions are to the 
right and down. No drawing is performed. 


PROCEDURE LineTo (h,v: INTEGER); 

LineTo draws a line from the current pen location to the location 
specified (in local coordinates) by h and v. The new pen location is 
(h,v) after the line is drawn. See the general discussion of drawing. 

If a region or polygon is open and being formed, its outline is 
infinitely thin and is not affected by the pnSize, pnMode, or pnPat. 
(See OpenRgn and OpenPoly. ) 

PROCEDURE Line (dh,dv: INTEGER); 

This procedure draws a line to the location that is a distance of dh 
horizontally and dv vertically from the current pen location; it calls 
LineTo (h+dh,v+dv) , where (h,v) is the current location. The positive 
directions are to the right and down. The pen location becomes the 
coordinates of the end of the line after the line is drawn. See the 
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general discussion of drawing. 

If a region or polygon is open and being formed, its outline is 
infinitely thin and is not affected by the pnSize, pnMode, or pnPat. 
(See OpenRgn and OpenPoly. ) 


Text-Drawing Routines 

Each grafPort has its own text characteristics, and all these 
procedures deal with those of the current port. 


PROCEDURE TextFont (font: INTEGER); 

TextFont sets the current grafPort's font (thePort~. txFont) to the 
given font number. The initial font number is 0, which represents the 
system font. 

PROCEDURE TextFace (face: Style); 

TextFace sets the current grafPort's character style (thePort~.txFace). 
The Style data type allows you to specify a set of one or more of the 
following predefined constants: bold, italic, underline, outline, 
shadow, condense, and extend. For example: 

TextFace([bold]) ; 

TextFace([ bold, italic]) ; 

TextFace (thePort*. txFace+[bold]) ; 

TextFace (thePort~. txFace-[boldj ) ; 

TextFace ( [ ] ) ; 

PROCEDURE TextMode (mode: INTEGER); 

TextMode sets the current grafPort 's transfer mode for drawing text 
( thePort * . txMode ) . The mode should be srcOr, srcXor, or srcBic. The 
initial transfer mode for drawing text is srcOr. 


{bold} 

{bold and italic} 

{whatever it was plus bold} 
{whatever it was but not bold} 
{normal} 


PROCEDURE Text Size (size: INTEGER); 

TextSize sets the current grafPort's type size (thePort*. txSize) to the 
given number of points. Any size may be specified, but the result will 
look best if the Font Manager has the font in that size (otherwise it 
will scale a size it does have). The next best result will occur if 
the given size is an even multiple of a size available for the font. 

If 0 is specified, the Font Manager will choose one of the available 
sizes — — whichever is closest to the system font size. The initial 
txSize setting is 0. 
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PROCEDURE SpaceExtra (extra: INTEGER); 

SpaceExtra sets the current grafPort's spExtra field, which specifies 
the number of pixels by which to widen each space in a line of text. 
This is useful when text is being fully justified (that is, aligned 
with both a left and a right margin). Consider, for example, a line 
that contains three spaces; if there would normally be six pixels 
between the end of the line and the right margin, you would call 
SpaceExtra(2) to print the line with full justification. The initia 
spExtra setting is 0. 

( hand) . 

SpaceExtra will also take a negative argument, but be 
careful not to narrow spaces so much that the text is 
unreadable . 


PROCEDURE DrawChar (ch: CHAR); 

DrawChar places the given character to the right of the pen location, 
with the left end of its base line at the pen's location, and advances 
the pen accordingly. If the character is not in the font, the font s 
missing symbol is drawn. 


PROCEDURE Drawstring (s: Str255); 

DrawString performs consecutive calls to DrawChar for each character in 
the supplied string; the string is placed beginning at the current pen 
location and extending right. No formatting (carriage returns, line 
feeds, etc.) is performed by QuickDraw. The pen location ends up to 
the right of the last character in the string. 


PROCEDURE DrawText (textBuf: QDPtr; f irstByte,byteCount : INTEGER); 

DrawText draws text from an arbitrary structure in memory specified by 
textBuf, starting firstByte bytes into the structure and continuing for 
byteCount bytes. The string of text is placed beginning at the current 
pen location and extending right. No formatting (carriage returns, 
line feeds, etc.) is performed by QuickDraw. The pen location ends up 
to the right of the last character in the string. 


FUNCTION CharWidth (ch: CHAR) : INTEGER; 

CharWidth returns the value that will be added to the pen horizontal 
coordinate if the specified character is drawn. CharWidth includes the 
effects of the stylistic variations set with TextFace; if you change 
these after determining the character width but before actually drawing 
the character, the predetermined width may not be correct. If the 
character is a space, CharWidth also includes the effect of SpaceExtra. 
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FUNCTION StringWidth (s: Str255) : INTEGER; 

StringWidth returns the width of the given text string, which it 
calculates by adding the CharWidths of all the characters in the string 
(see above). This value will be added to the pen horizontal coordinate 
if the specified string is drawn. 


FUNCTION TextWidth (textBuf: QDPtr; f irstByte,byteCount : INTEGER) : 
INTEGER; 

TextWidth returns the width of the text stored in the arbitrary 
structure in memory specified by textBuf, starting firstByte bytes into 
the structure and continuing for byteCount bytes. It calculates the 
width by adding the CharWidths of all the characters in the text. (See 
CharWidth, above.) 


PROCEDURE GetFontlnfo (VAR info: Fontlnfo); 

GetFontlnfo returns the following information about the current 
grafPort's character font, taking into consideration the style and size 
in which the characters will be drawn: the ascent, descent, maximum 
character width (the greatest distance the pen will move when a 
character is drawn), and leading (the vertical distance between the 
descent line and the ascent line below it), all in pixels. The 
Fontlnfo data structure is defined as: 

TYPE Fontlnfo « RECORD 

ascent : INTEGER ; 
descent: INTEGER; 
widMax: INTEGER; 
leading: INTEGER 
END; 


Drawing in Color 


These routines will enable applications to do color drawing in the 
future when Apple supports color output devices for the Macintosh. All 
nonwhite colors will appear as black on black-and-white output devices. 


PROCEDURE ForeColor (color: Longlnt); 


ForeColor 
grafPort ( 
colors are 
blueColor, 
foreground 


sets the foreground color for all drawing in the current 
~thePort .fgColor) to the given color. The following standard 
predefined: blackColor, whiteColor, redColor, greenColor, 
cyanColor , magentaColor , and yellowColor. The initial 
color is blackColor. 
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PROCEDURE BackColor (color: Longlnt); 

BackColor sets the background color for all drawing in the current 
grafPort (~thePort .bkColor) to the given color. Eight standard colors 
are predefined (see ForeColor above). The initial background color is 
whiteColor . 


PROCEDURE ColorBit (whichBit: INTEGER); 

ColorBit is called by printing software for a color printer, or other 
color-imaging software, to set the current graf Port's colrBit field to 
whichBit; this tells QuickDraw which plane of the color picture to draw 
into. QuickDraw will draw into the plane corresponding to bit number 
whichBit. Since QuickDraw can support output devices that have up to 
32 bits of color information per pixel, the possible range of values 
for whichBit is 0 through 31. The initial value of the colrBit field 
is 0. 


Calculations with Rectangles 

Calculation routines are independent of the current coordinate system; 
a calculation will operate the same regardless of which grafPort is 
active. 

( hand) 

Remember that if the parameters to one of the calculation 
routines were defined in different grafPort s, you must 
first adjust them to be in the same coordinate system. 

If you do not adjust them, the result returned by the 
routine may be different from what you see on the screen. 

To adjust to a common coordinate system, see 
LocalToGlobal and GlobalToLocal under "Calculations with 
Points" below. 


PROCEDURE SetRect (VAR r: Rect; left, top, right, bottom: INTEGER); 

SetRect assigns the four boundary coordinates to the rectangle. The 
result is a rectangle with coordinates (left, top, right , bottom) • 

This procedure is supplied as a utility to help you shorten your 
program text. If you want a more readable text at the expense of 
length, you can assign integers (or points) directly into the 
rectangle's fields. There is no significant code size or execution 
speed advantage to either method; one's just easier to write, and the 
other's easier to read. 


PROCEDURE Off setRect (VAR r: Rect; dh,dv: INTEGER); 

OffsetRect moves the rectangle by adding dh to each horizontal 
coordinate and dv to each vertical coordinate. If dh and dv are 
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positive, the movement is to the right and down; if either is negative, 
the corresponding movement is in the opposite direction. The rectangle 
retains its shape and size; it^s merely moved on the coordinate plane. 
This does not affect the screen unless you subsequently call a routine 
to draw within the rectangle. 


PROCEDURE InsetRect (VAR r: Rect ; dh,dv: INTEGER); 

InsetRect shrinks or expands the rectangle. The left and right sides 
are moved in by the amount specified by dh; the top and bottom are 
moved towards the center by the amount specified by dv. If dh or dv is 
negative, the appropriate pair of sides is moved outwards instead of 
inwards. The effect is to alter the size by 2*dh horizontally and 2*dv 
vertically, with the rectangle remaining centered in the same place on 
the coordinate plane. 

If the resulting width or height becomes less than 1, the rectangle is 
set to the empty rectangle (0,0, 0,0). 


FUNCTION SectRect (srcRectA, srcRectB: Rect; VARdstRect: Rect) : 

BOOLEAN ; 

SectRect calculates the rectangle that Is the intersection of the two 
input rectangles, and returns TRUE if they indeed intersect or FALSE if 
they do not. Rectangles that " touch” at a line or a point are not 
considered intersecting, because their intersection rectangle (really, 
in this case, an intersection line or point) does not enclose any bits 
on the bitMap. 

If the rectangles do not intersect, the destination rectangle is set to 
(0,0, 0,0). SectRect works correctly even if one of the source 
rectangles is also the destination. 


PROCEDURE UnionRect ( srcRectA, srcRectB: Rect; VAR dstRect: Rect); 

UnionRect calculates the smallest rectangle which encloses both input 
rectangles. It works correctly even if one of the source rectangles is 
also the destination. 


FUNCTION PtlnRect (pt: Point; r: Rect) : BOOLEAN; 

PtlnRect determines whether the pixel below and to the right of the 
given coordinate point is enclosed in the specified rectangle, and 
returns TRUE if so or FALSE if not. 


PROCEDURE Pt2Rect (ptA,ptB: Point; VAR: dstRect: Rect); 

Pt2Rect returns the smallest rectangle which encloses the two input 
points . 


3/2/83 Espinosa-Rose 


CONFIDENTIAL 


/QUICK. 2/QUIKDRAW . 5 



48 


QuickDraw Programmers Guide 


PROCEDURE Pt To Angle (r: Rect ; pt: Point; VAR angle: INTEGER); 

PtToAngle calculates an integer angle between a line from the center of 
the rectangle to the given point and a line from the center of the 
rectangle pointing straight up (12 o'clock high). The angle is in 
degrees from 0 to 359, measured clockwise from 12 o clock, with 90 
degrees at 3 o'clock, 180 at 6 o'clock, and 270 at 9 o clock. Other 
angles are measured relative to the rectangle: If the line to the 
given point goes through the top right corner of the rectangle, the^ 
angle returned is 45 degrees, even if the rectangle is not square; if 
it goes through the bottom right corner, the angle is 135 degrees, and 
so on (see Figure 18). 


angle = 45 



Figure 18. PtToAngle 

The angle returned might be used as input to one of the procedures that 
manipulate arcs and wedges, as described below under Graphic 
Operations on Arcs and Wedges*’ . 


FUNCTION Equal Rect ( rectA, rectB: Rect) : BOOLEAN; 

EqualRect compares the two rectangles and returns TRUE if they are 
equal or FALSE if not. The two rectangles must have identical boundary 
coordinates to be considered equal. 


FUNCTION EmptyRect (r: Rect) : BOOLEAN; 

EmptyRect returns TRUE if the given rectangle is an empty rectangle or 
FALSE if not. A rectangle is considered empty if the bottom coordinate 
is equal to or less than the top or the right coordinate is equal to or 
less than the left. 
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Graphic Operations on Rectangles 

These procedures perform graphic operations on rectangles. See also 
ScrollRect under ”Bit Transfer Operations”. 


PROCEDURE FraraeRect (r: Rect); 

FrameRect draws a hollow outline just inside the specified rectangle, 
using the current grafPort^s pen pattern, mode, and size. The outline 
is as wide as the pen width and as tall as the pen height. It is drawn 
with the pnPat, according to the pattern transfer mode specified by 
pnMode. The pen location is not changed by this procedure. 

If a region is open and being formed, the outside outline of the new 
rectangle is mathematically added to the region^s boundary. 


PROCEDURE PaintRect (r: Rect); 

PaintRect paints the specified rectangle with the current grafPort^s 
pen pattern and mode. The rectangle on the bitMap is filled with the 
pnPat, according to the pattern transfer mode specified by pnMode. The 
pen location is not changed by this procedure. 


PROCEDURE EraseRect (r: Rect); 

EraseRect paints the specified rectangle with the current grafPort^s 
background pattern bkPat (in pat Copy mode). The graf Port's pnPat and 
pnMode are ignored; the pen location is not changed. 


PROCEDURE InvertRect (r: Rect); 

InvertRect inverts the pixels enclosed by the specified rectangle: 
every white pixel becomes black and every black pixel becomes white. 
The grafPort^s pnPat, pnMode, and bkPat are all ignored; the pen 
location is not changed. 


PROCEDURE FillRect (r: Rect; pat: Pattern); 

FillRect fills the specified rectangle with the given pattern (in 
patCopy mode). The grafPort's pnPat, pnMode, and bkPat are all 
ignored; the pen location is not changed. 
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Graphic Operations on Ovals __ 

Ovals are drawn inside rectangles that you specify. If the rectangle 
you specify is square, QuickDraw draws a circle. 


PROCEDURE FrameOval (r: Rect); 

FrameOval draws a hollow outline just inside the oval that fits inside 
the specified rectangle, using the current graf Port's pen pattern, 
mode, and size. The outline is as wide as the pen width and as tall as 
the pen height. It is drawn with the pnPat, according to the pattern 
transfer mode specified by pnMode. The pen location is not changed by 
this procedure. 

If a region is open and being formed, the outside outline of the new 
oval is mathematically added to the region's boundary. 


PROCEDURE PaintOval (r: Rect); 

PaintOval paints an oval just inside the specified rectangle with the 
current grafPort's pen pattern and mode. The oval on the bitMap is 
filled with the pnPat, according to the pattern transfer mode specified 
by pnMode. The pen location is not changed by this procedure. 


PROCEDURE EraseOval (r: Rect); 

EraseOval paints an oval just inside the specified rectangle with the 
current grafPort's background pattern bkPat (in patCopy mode). The 
grafPort's pnPat and pnMode are ignored; the pen location is not 
changed . 

PROCEDURE InvertOval (r: Rect); 

InvertOval inverts the pixels enclosed by an oval just inside the 
specified rectangle: every white pixel becomes black and every black 
pixel becomes white. The graf Port's pnPat, pnMode, and bkPat are all 
ignored; the pen location is not changed. 


PROCEDURE FillOval (r: Rect; pat: Pattern); 

FillOval fills an oval just inside the specified rectangle with the 
given pattern (in patCopy mode). The grafPort's pnPat, pnMode, and 
bkPat are all ignored; the pen location is not changed. 
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Graphic Operations on Rounded-Corner Rectangles 


PROCEDURE FrameRoundRect (r: Rect ; ovalWidth, ovalHeight : INTEGER); 

FrameRoundRect draws a hollow outline just inside the specified 
rounded-corner rectangle, using the current grafPort's pen pattern, 
mode, and size. OvalWidth and ovalHeight specify the diameters of 
curvature for the corners (see Figure 19). The outline is as wide as 
the pen width and as tall as the pen height. It is drawn with the 
pnPat, according to the pattern transfer mode specified by pnMode. The 
pen location is not changed by this procedure. 


ovalW ldth q YalHeigftt 




Figure 19. Rounded-Corner Rectangle 

If a region is open and being formed, the outside outline of the new 
rounded-corner rectangle is mathematically added to the region's 
boundary. 


PROCEDURE PaintRoundRect (r: Rect; ovalWidth, ovalHeight : INTEGER); 

PaintRoundRect paints the specified rounded-corner rectangle with the 
current grafPort's pen pattern and mode. OvalWidth and ovalHeight 
specify the diameters of curvature for the corners. The rounded-corner 
rectangle on the bitMap is filled with the pnPat, according to the 
pattern transfer mode specified by pnMode. The pen location is not 
changed by this procedure. 


PROCEDURE EraseRoundRect (r: Rect; ovalWidth, ovalHeight : INTEGER); 

EraseRoundRect paints the specified rounded-corner rectangle with the 
current grafPort's background pattern bkPat (in patCopy mode). 
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OvalWidth and ovalHeight specify the diameters of curvature for the 
corners. The grafPort's pnPat and pnMode are ignored; the pen location 
is not changed. 


PROCEDURE InvertRoundRect (r: Rect ; ovalWidth, ovalHeight : INTEGER); 

InvertRoundRect inverts the pixels enclosed by the specified 
rounded-corner rectangle: every white pixel becomes black and every 
black pixel becomes white. OvalWidth and ovalHeight specify the 
diameters of curvature for the corners. The grafPort s pnPat, pnMode, 
and bkPat are all ignored; the pen location is not changed. 


PROCEDURE FillRoundRect (r: Rect; ovalWidth, ovalHeight : INTEGER; pat: 
Pattern) ; 

FillRoundRect fills the specified rounded-corner rectangle with the 
given pattern (in patCopy mode). OvalWidth and ovalHeight specify the 
diameters of curvature for the corners. The grafPort s pnPat, pnMode, 
and bkPat are all ignored; the pen location is not changed. 


Graphic Operations on Arcs and Wedges 

These procedures perform graphic operations on arcs and wedge-shaped 
sections of ovals. See also PtToAngle under Calculations with 
Rectangles”. 


PROCEDURE FrameArc (r: Rect; s tart Angle ,arcAngle : INTEGER); 


FrameArc draws an arc of the oval that fits inside the specified 
rectangle, using the current grafPort's pen pattern, mode, and size. 
Start Angle indicates where the arc begins and is treated mod 360. 
ArcAngle defines the extent of the arc. The angles are given in 
positive or negative degrees; a positive angle goes clockwise , ^ while a 
negative angle goes counterclockwise. Zero degrees is at 12 o clock 
high, 90 (or -270) is at 3 o'clock, 180 (or -180) is at 6 o'clock, and 
270 (or -90) is at 9 o'clock. Other angles are measured relative to 
the enclosing rectangle: a line from the center of the rectangle 
through its top right corner is at 45 degrees, even if the rectangle is 
not square; a line through the bottom right corner is at 135 degrees, 
and so on (see Figure 20). 
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st&rtAnele = 0 



PaintArc 


Figure 20. Operations on Arcs and Wedges 

The arc is as wide as the pen width and as tall as the pen height. It 
is drawn with the pnPat, according to the pattern transfer mode 
specified by pnMode. The pen location is not changed by this 
procedure. 

( eye) 

FrameArc differs from other QuickDraw procedures that 
frame shapes in that the arc is not mathematically added 
to the boundary of a region that is open and being 
formed. 


PROCEDURE PaintArc (r: Rect ; startAngle , arcAngle : INTEGER); 

PaintArc paints a wedge of the oval just inside the specified rectangle 
with the current graf Port's pen pattern and mode. StartAngle and 
arcAngle define the arc of the wedge as in FrameArc. The wedge on the 
bitMap is filled with the pnPat, according to the pattern transfer mode 
specified by pnMode. The pen location is not changed by this 
procedure. 


PROCEDURE EraseArc (r: Rect; startAngle , arcAngle : INTEGER); 

EraseArc paints a wedge of the oval just inside the specified rectangle 
with the current graf Port's background pattern bkPat (in patCopy mode). 
StartAngle and arcAngle define the arc of the wedge as in FrameArc. 

The grafPort's pnPat and pnMode are ignored; the pen location is not 
changed . 


3/2/83 Espinosa-Rose 


CONFIDENTIAL 


/QUICK . 2 /QUIKDRAW . 5 




54 


QuickDraw Programmer's Guide 


PROCEDURE InvertArc (r: Rect ; StartAngle .arcAngle : INTEGER); 

InvertArc inverts the pixels enclosed by a wedge of the oval just 
inside the specified rectangle: every white pixel becomes black and 
every black pixel becomes white. StartAngle and arcAngle define the 
arc of the wedge as in FrameArc. The grafPort's pnPat, pnMode, and 
bkPat are all ignored; the pen location is not changed. 


PROCEDURE FillArc (r: Rect; start Angle, arcAngle: INTEGER; pat: 
Pattern) ; 

FillArc fills a wedge of the oval just inside the specified rectangle 
with the given pattern (in patCopy mode). StartAngle and arcAngle 
define the arc of the wedge as in FrameArc. The grafPort s pnPat, 
pnMode, and bkPat are all ignored; the pen location is not changed. 


Calculations with Regions 


Remember that if the parameters to one of the calculation 
routines were defined in different grafPorts, you must 
first adjust them to be in the same coordinate system. 

If you do not adjust them, the result returned by the 
routine may be different from what you see on the screen. 
To adjust to a common coordinate system, see 
LocaltoGlobal and GlobalToLocal under "Calculations with 
Points” below. 


FUNCTION NewRgn : RgnHandle; 

NewRgn allocates space for a new, dynamic, variable-size region, 
initializes it to the empty region (0, 0,0,0). and returns a handle to 
the new region. Only this function creates new regions; all other 
procedures just alter the size and shape of regions you create. 
OpenPort calls NewRgn to allocate space for the port's visRgn and 
clipRgn. 

( eye) 

Except when using visRgn or clipRgn, you MUST call NewRgn 
before specifying a region's handle in any drawing or 
calculation procedure. 


( 


eye) 

Never refer to a region without using its handle. 


PROCEDURE DisposeRgn (rgn: RgnHandle); 

DisposeRgn deallocates space for the region whose handle is supplied, 
and returns the memory used by the region to the free memory pool. Use 
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this only after you are completely through with a temporary region. 
( eye) 

Never use a region once you have deallocated it, or you 
will risk being hung by dangling pointers! 


PROCEDURE CopyRgn (srcRgn,dstRgn: RgnHandle); 

CopyRgn copies the mathematical structure of srcRgn into dstRgn; that 
is, it makes a duplicate copy of srcRgn. Once this is done, srcRgn may 
be altered (or even disposed of) without affecting dstRgn. COPYRGN 
DOES NOT CREATE THE DESTINATION REGION: you must use NewRgn to create 
the dstRgn before you call CopyRgn. 


PROCEDURE Se tEmpt yRgn ( rgn : RgnHand le ) ; 

SetEmptyRgn destroys the previous structure of the given region, then 
sets the new structure to the empty region (0, 0,0,0). 


PROCEDURE SetRectRgn (rgn: RgnHandle; left, top, right, bottom: INTEGER); 

SetRectRgn destroys the previous structure of the given region, then 
sets the new structure to the rectangle specified by left, top, right, 
and bottom. 

If the specified rectangle is empty (i.e., left^right or top>=bottom) , 
the region is set to the empty region (0,0, 0,0). 


PROCEDURE RectRgn (rgn: RgnHandle; r: Rect); 

RectRgn destroys the previous structure of the given region, then sets 
the new structure to the rectangle specified by r. This is 
operationally synonymous with SetRectRgn, except the input rectangle is 
defined by a rectangle rather than by four boundary coordinates. 


PROCEDURE OpenRgn; 

OpenRgn tells QuickDraw to allocate temporary space and start saving 
lines and framed shapes for later processing as a region definition. 
While a region is open, all calls to Line, LineTo, and the procedures 
that draw framed shapes (except arcs) affect the outline of the region. 
Only the line endpoints and shape boundaries affect the region 
definition; the pen mode, pattern, and size do not affect it. In fact, 
OpenRgn calls HidePen, so no drawing occurs on the screen while the 
region is open (unless you called ShowPen just after OpenRgn, or you 
called ShowPen previously without balancing it by a call to HidePen). 
Since the pen hangs below and to the right of the pen location, drawing 
lines with even the smallest pen will change bits that lie outside the 
region you define. 
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The outline of a region is mathematically defined and infinitely thin, 
and separates the bitMap into two groups of bits: those within the 
region and those outside it. A region should consist of one or more 
closed loops. Each framed shape itself constitutes a loop. Any lines 
drawn with Line or LineTo should connect with each other or with a 
framed shape. Even though the on-screen presentation of a region is 
clipped, the definition of a region is not; you can define a region 
anywhere on the coordinate plane with complete disregard for the 
location of various grafPort entities on that plane. 

When a region is open, the current grafPort's rgnSave field contains a 
handle to information related to the region definition. If you want to 
temporarily disable the collection of lines and shapes, you can save 
the current value of this field, set the field to NIL, and later 
restore the saved value to resume the region definition. 

( eye) 

Do not call OpenRgn while another region is already open. 

All open regions but the roost recent will behave 

strangely. 


PROCEDURE CloseRgn (dstRgn: RgnHandle); 

CloseRgn stops the collection of lines and framed shapes, organizes 
them into a region definition, and saves the resulting region into the 
region indicated by dstRgn. You should perform one and only one 


CloseRgn for every OpenRgn. CloseRgn calls 
HidePen call made by OpenRgn. 

Here's an example of how to create and open 
shape, close the region, and draw it: 

barbel 1 : = NewRgn ; 

OpenRgn; 

SetRect ( tempRect ,20,20,30,50) ; 
FrameOval ( tempRect ) ; 

SetRect (tempRect ,30,30,80,40) ; 
FrameRect ( tempRect ) ; 

SetRect ( tempRect ,80,20,90,50); 
FrameOval ( tempRect ) ; 
CloseRgn(barbell) ; 

FillRgn( barbell, black) ; 
DisposeRgn(barbell) ; 


ShowPen, balancing the 

a region, define a barbell 

{make a new region} 

{begin collecting stuff} 

{form the left weight} 

{form the bar} 

{form the right weight} 

{we're done; save in barbell} 
{draw it on the screen} 

{we don't need you anymore...} 


PROCEDURE Of f setRgn (rgn: RgnHandle; dh,dv: INTEGER); 

OffsetRgn moves the region on the coordinate plane, a distance of dh 
horizontally and dv vertically. This does not affect the screen unless 
you subsequently call a routine to draw the region. If dh and dv are 
positive, the movement is to the right and down; if either is negative, 
the corresponding movement is in the opposite direction. The region 
retains its size and shape. 
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( hand ) 

Of f setRgn is an especially efficient operation, because 
most of the data defining a region is stored relative to 
rgnBBox and so isn't actually changed by OffsetRgn. 


PROCEDURE InsetRgn (rgn: RgnHandle; dh,dv: INTEGER); 

InsetRgn shrinks or expands the region* All points on the region 
boundary are moved inwards a distance of dv vertically and dh 
horizontally; if dh or dv is negative, the points are moved outwards in 
that direction. InsetRgn leaves the region "centered” at the same 
position, but moves the outline in (for positive values of dh and dv) 
or out (for negative values of dh and dv). InsetRgn of a rectangular 
region works just like InsetRect. 


PROCEDURE SectRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle); 

SectRgn calculates the intersection of two regions and places the 
intersection in a third region. THIS DOES NOT CREATE THE DESTINATION 
REGION: you must use NewRgn to create the dstRgn before you call 

SectRgn. The dstRgn can be one of the source regions, if desired. 

If the regions do not intersect, or one of the regions is empty, the 
destination is set to the empty region (0,0, 0,0). 


PROCEDURE UnionRgn (srcRgnA, srcRgnB, dstRgn: RgnHandle); 

UnionRgn calculates the union of two regions and places the union in a 
third region. THIS DOES NOT CREATE THE DESTINATION REGION: you must 
use NewRgn to create the dstRgn before you call UnionRgn. The dstRgn 
can be one of the source regions, if desired. 

If both regions are empty, the destination is set to the empty region 

( 0 , 0 , 0 , 0 ). 


PROCEDURE DiffRgn (srcRgnA, srcRgnB, dstRgn: RgnHandle); 

DiffRgn subtracts srcRgnB from srcRgnA and places the difference in a 
third region. THIS DOES NOT CREATE THE DESTINATION REGION: you must 
use NewRgn to create the dstRgn before you call DiffRgn. The dstRgn 
can be one of the source regions, if desired. 

If the first source region is empty, the destination is set to the 
empty region (0, 0,0,0). 


PROCEDURE XorRgn (srcRgnA, srcRgnB, dstRgn: RgnHandle); 

XorRgn calculates the difference between the union and the intersection 
of two regions and places the result in a third region. THIS DOES NOT 
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CREATE THE DESTINATION REGION: you must use NewRgn to create the 
dstRgn before you call XorRgn. The dstRgn can be one of the source 
regions, if desired. 

If the regions are coincident, the destination is set to the empty 
region (0,0, 0,0). 


FUNCTION PtlnRgn (pt: Point; rgn: RgnHandle) : BOOLEAN; 

PtlnRgn checks whether the pixel below and to the right of the given 
coordinate point is within the specified region, and returns TRUE if sc 
or FALSE if not. 


FUNCTION RectlnRgn (r: Rect ; rgn: RgnHandle) : BOOLEAN; 

RectlnRgn checks whether the given rectangle intersects the specified 
region, and returns TRUE if the intersection encloses at least one bit 
or FALSE if not. 


FUNCTION EqualRgn (rgnA,rgnB: RgnHandle) : BOOLEAN; 

EqualRgn compares the two regions and returns TRUE if they are equal or 
FALSE if not. The two regions must have identical sizes, shapes, and 
locations to be considered equal. Any two empty regions are always 
equal . 


FUNCTION EmptyRgn (rgn: RgnHandle) : BOOLEAN; 

EmptyRgn returns TRUE if the region is an empty region or FALSE if not. 
Some of the circumstances in which an empty region can be created are: 
a NewRgn call; a CopyRgn of an empty region; a SetRectRgn or RectRgn 
with an empty rectangle as an argument; CloseRgn without a previous 
OpenRgn or with no drawing after an OpenRgn; OffsetRgn of an empty 
region; InsetRgn with an empty region or too large an inset; SectRgn of 
nonintersecting regions; UnionRgn of two empty regions; and DiffRgn or 
XorRgn of two identical or nonintersecting regions. 


Graphic Operations on Regions 

These routines all depend on the coordinate system of the current 
grafPort. If a region is drawn In a different grafPort than the one in 
which it was defined, it may not appear in the proper position inside 
the port. 


PROCEDURE FrameRgn (rgn: RgnHandle); 

FrameRgn draws a hollow outline just inside the specified region, using 
the current grafPort^s pen pattern, mode, and size. The outline is as 
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wide as the pen width and as tall as the pen height; under no 
circumstances will the frame go outside the region boundary. The pen 
location is not changed by this procedure. 

If a region is open and being formed, the outside outline of the region 
being framed is mathematically added to that region's boundary. 


PROCEDURE PaintRgn (rgn: RgnHandle); 

PaintRgn paints the specified region with the current grafPort's pen 
pattern and pen mode. The region on the bitMap is filled with the 
pnPat, according to the pattern transfer mode specified by pnMode. The 
pen location is not changed by this procedure. 


PROCEDURE EraseRgn (rgn: RgnHandle); 

EraseRgn paints the specified region with the current grafPort's 
background pattern bkPat (in patCopy mode). The grafPort's pnPat and 
pnMode are ignored; the pen location is not changed. 


PROCEDURE InvertRgn (rgn: RgnHandle); 

InvertRgn inverts the pixels enclosed by the specified region: every 
white pixel becomes black and every black pixel becomes white. The 
grafPort's pnPat, pnMode, and bkPat are all ignored; the pen location 
is not changed. 


PROCEDURE FillRgn (rgn: RgnHandle; pat: Pattern); 

FillRgn fills the specified region with the given pattern (in patCopy 
mode). The grafPort's pnPat, pnMode, and bkPat are all ignored; the 
pen location is not changed. 


Bit Transfer Operations 


PROCEDURE ScrollRect (r: Rect; dh,dv: INTEGER; updateRgn: RgnHandle); 

ScrollRect shifts ("scrolls") those bits inside the intersection of the 
specified rectangle, visRgn, clipRgn, portRect, and portBits. bounds. 

The bits are shifted a distance of dh horizontally and dv vertically. 
The positive directions are to the right and down. No other bits are 
affected. Bits that are shifted out of the scroll area are lost; they 
are neither placed outside the area nor saved. The grafPort's 
background pattern bkPat fills the space created by the scroll. In 
addition, updateRgn is changed to the area filled with bkPat (see 
Figure 21). 
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Figure 21. Scrolling 

Figure 21 shows that the pen location after a ScrollRect is in a 
different position relative to what was scrolled in the rectangle. The 
entire scrolled item has been moved to different coordinates. To 
restore it to its coordinates before the ScrollRect, you can use the 
SetOrigin procedure. For example, suppose the dstRect here is the 
portRect of the grafPort and its top left corner is at (95,120). 
SetOrigin(105, 115) will offset the coordinate system to compensate for 
the scroll. Since the clipRgn and pen location are not offset, they 
move down and to the left. 


PROCEDURE CopyBits (srcBits,dstBits: BitMap; srcRect , dstRect : Rect ; 
mode : INTEGER ; maskRgn : RgnHand le ) ; 

CopyBits transfers a bit image between any two bitMaps and clips the 
result to the area specified by the maskRgn parameter. The transfer 
may be performed in any of the eight source transfer modes. The result 
is always clipped to the maskRgn and the boundary rectangle of the 
destination bitMap; if the destination bitMap is the current grafPort's 
portBits, it is also clipped to the intersection of the grafPort s 
clipRgn and visRgn. If you do not want to clip to a maskRgn, just pass 
NIL for the maskRgn parameter. 

The dstRect and maskRgn coordinates are in terms of the dstBits. bounds 
coordinate system, and the srcRect coordinates are in terms of the 
srcBits .bounds coordinates • 

The bits enclosed by the source rectangle are transferred into the 
destination rectangle according to the rules of the chosen mode. The 
source transfer modes are as follows: 

srcCopy srcXor notSrcCopy notSrcXor 

srcOr srcBic notSrcOr notSrcBic 
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The source rectangle is completely aligned with the destination 
rectangle; if the rectangles are of different sizes, the bit image is 
expanded or shrunk as necessary to fit the destination rectangle. For 
example, if the bit image is a circle in a square source rectangle, and 
the destination rectangle is not square, the bit image appears as an 
oval in the destination (see Figure 22). 



fliasJfJSgn 


Source MM&p 


Itestiristioii BitM&p 





Figure 22. Operation of CopyBits 


Pictures 


FUNCTION OpenPicture (picFrame: Rect) : PicHandle; 

OpenPicture returns a handle to a new picture which has the given 
rectangle as its picture frame, and tells QuickDraw to start saving as 
the picture definition all calls to drawing routines and all picture 
comments (if any). 


OpenPicture calls HidePen, so no drawing occurs on the screen while the 
picture is open (unless you call ShowPen just after OpenPicture, or you 
called ShowPen previously without balancing it by a call to HidePen). 

When a picture is open, the current grafPort's picSave field contains a 
handle to information related to the picture definition. If you want 
to temporarily disable the collection of routine calls and picture 
comments, you can save the current value of this field, set the field 
to NIL, and later restore the saved value to resume the picture 
definition. 

( eye) 

Do not call OpenPicture while another picture is already 
open. 




3/2/83 Espinosa-Rose 


CONFIDENTIAL 


/QUICK. 2/QUIKDRAW . 6 




62 


QuickDraw Programmer's Guide 


PROCEDURE ClosePicture; 

ClosePicture tells QuickDraw to stop saving routine calls and picture 
comments as the definition of the currently open picture. You should 
perform one and only one ClosePicture for every OpenPicture. 
ClosePicture calls ShowPen, balancing the HidePen call made by 
OpenPicture. 


PROCEDURE PicComment (kind .dataSize : INTEGER; dataHandle: QDHandle); 

PicComment inserts the specified comment into the definition of the 
currently open picture. Kind identifies the type of comment. 

DataHandle is a handle to additional data if desired, and dataSize is 
the size of that data in bytes. If there is no additional data for the 
comment, dataHandle should be NIL and dataSize should be 0 . The 
application that processes the comment must include a procedure to do 
the processing and store a pointer to the procedure in the data 
structure pointed to by the grafProcs field of the grafPort (see 
"Customizing QuickDraw Operations”). 


PROCEDURE DrawPicture (myPicture: PicHandle; dstRect: Rect); 

DrawPicture draws the given picture to scale in dstRect, expanding or 
shrinking it as necessary to align the borders of the picture frame 
with dstRect. DrawPicture passes any picture comments to the procedure 
accessed indirectly through the grafProcs field of the grafPort (see 
PicComment above). 


PROCEDURE KillPicture (myPicture: PicHandle); 

KillPicture deallocates space for the picture whose handle is supplied, 
and returns the memory used by the picture to the free memory pool. 

Use this only when you are completely through with a picture. 


Calculations with Polygons 


FUNCTION OpenPoly : PolyHandle; 

OpenPoly returns a handle to a new polygon and tells QuickDraw to start 
saving the polygon definition as specified by calls to line-drawing 
routines. While a polygon is open, all calls to Line and LineTo affect 
the outline of the polygon. Only the line endpoints affect the polygon 
definition; the pen mode, pattern, and size do not affect it. In fact, 
OpenPoly calls HidePen, so no drawing occurs on the screen while the 
polygon is open (unless you call ShowPen just after OpenPoly, or you 
called ShowPen previously without balancing it by a call to HidePen). 
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A polygon should consist of a sequence of connected lines. Even though 
the on-screen presentation of a polygon is clipped, the definition of a 
polygon is not; you can define a polygon anywhere on the coordinate 
plane with complete disregard for the location of various grafPort 
entities on that plane. 

When a polygon is open, the current grafPort's polySave field contains 
a handle to information related to the polygon definition. If you want 
to temporarily disable the polygon definition, you can save the current 
value of this field, set the field to NIL, and later restore the saved 
value to resume the polygon definition. 

( eye) 

Do not call OpenPoly while another polygon is already 
open. 


PROCEDURE ClosePoly; 


ClosePoly tells QuickDraw to stop saving the definition of the 
currently open polygon and computes the polyBBox rectangle. You should 
perform one and only one ClosePoly for every OpenPoly. ClosePoly calls 
ShowPen, balancing the HidePen call made by OpenPoly. 


Here's an example of how to open a polygon, define it as a triangle, 
close it, and draw it: 


triPoly := OpenPoly; 
MoveTo ( 300 , 100 ) ; 
LineTo(400,200) ; 
LineTo(200,200) ; 
LineTo(300, 100) ; 
ClosePoly; 

FillPoly( triPoly, gray) ; 
KillPoly( triPoly); 


{save handle and begin collecting stuff} 
{ move to first point and } 

{ form } 

{ the } 

{ triangle } 

{stop collecting stuff} 

{draw it on the screen} 

{we're all done} 


PROCEDURE KillPoly (poly: PolyHandle); 

KillPoly deallocates space for the polygon whose handle is supplied, 
and returns the memory used by the polygon to the free memory pool. 
Use this only after you are completely through with a polygon. 


PROCEDURE OffsetPoly (poly: PolyHandle; dh,dv: INTEGER); 

OffsetPoly moves the polygon on the coordinate plane, a distance of dh 
horizontally and dv vertically. This does not affect the screen unless 
you subsequently call a routine to draw the polygon. If dh and dv are 
positive, the movement is to the right and down; if either is negative, 
the corresponding movement is in the opposite direction. The polygon 
retains its shape and size. 
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( hand ) 

OffsetPoly is an especially efficient operation, because 
the data defining a polygon is stored relative to 
polyStart and so isn"t actually changed by OffsetPoly* 


Graphic Operations on Polygons 


PROCEDURE FramePoly (poly: PolyHandle); 

FramePoly plays back the line-drawing routine calls that define the 
given polygon, using the current grafPort"s pen pattern, mode, and 
size. The pen will hang below and to the right of each point on the 
boundary of the polygon; thus, the polygon drawn will extend beyond the 
right and bottom edges of poly^.polyBBox by the pen width and pen 
height, respectively# All other graphic operations occur strictly 
within the boundary of the polygon, as for other shapes. You can see 
this difference in Figure 23, where each of the polygons is shown with 
its polyBBox. 



Figure 23. Drawing Polygons 

If a polygon is open and being formed, FramePoly affects the outline of 
the polygon just as if the line-drawing routines themselves had been 
called. If a region is open and being formed, the outside outline of 
the polygon being framed is mathematically added to the region s 
boundary. 


PROCEDURE PaintPoly (poly: PolyHandle); 

PaintPoly paints the specified polygon with the current grafPort"s pen 
pattern and pen mode. The polygon on the bitMap is filled with the 
pnPat, according to the pattern transfer mode specified by pnMode . The 


3/2/83 Espinosa-Rose 


CONFIDENTIAL 


/QUICK.2/QUIKDRAW .6 


QUICKDRAW ROUTINES 


65 


pen location is not changed by this procedure. 


PROCEDURE ErasePoly (poly: PolyHandle); 

ErasePoly paints the specified polygon with the current grafPort's 
background pattern bkPat (in patCopy mode). The pnPat and pnMode are 
ignored; the pen location is not changed. 


PROCEDURE InvertPoly (poly: PolyHandle); 

InvertPoly inverts the pixels enclosed by the specified polygon: every 
white pixel becomes black and every black pixel becomes white. The 
grafPort's pnPat, pnMode, and bkPat are all ignored; the pen location 
is not changed. 


PROCEDURE FillPoly (poly: PolyHandle; pat: Pattern); 

FillPoly fills the specified polygon with the given pattern (in patCopy 
mode). The grafPort^s pnPat, pnMode, and bkPat are all ignored; the 
pen location is not changed. 


Calculations with Points 


PROCEDURE AddPt (srcPt: Point; VAR dstPt: Point); 

AddPt adds the coordinates of srcPt to the coordinates of dstPt, and 
returns the result in dstPt. 


PROCEDURE SubPt (srcPt: Point; VAR dstPt: Point); 

SubPt subtracts the coordinates of srcPt from the coordinates of dstPt, 
and returns the result in dstPt. 

PROCEDURE SetPt (VAR pt : Point; h,v: INTEGER); 

SetPt assigns two integer coordinates to a variable of type Point. 


FUNCTION EqualPt (ptA,ptB: Point) : BOOLEAN; 

EqualPt compares the two points and returns true if they are equal or 
FALSE if not. 
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PROCEDURE LocalToGlobal (VAR pt : Point); 

LocalToGlobal converts the given point from the current grafPort's 
local coordinate system into a global coordinate system with the origin 
(0,0) at the top left corner of the port's bit image (such as the 
screen). This global point can then be compared to other global 
points, or be changed into the local coordinates of another grafPort. 

Since a rectangle is defined by two points, you can convert a rectangle 
into global coordinates by performing two LocalToGlobal calls. You can 
also convert a rectangle, region, or polygon into global coordinates by 
calling OffsetRect, OffsetRgn, or OffsetPoly. For examples, see 
GlobalToLocal below. 


PROCEDURE GlobalToLocal (VAR pt : Point); 

GlobalToLocal takes a point expressed in global coordinates (with the 
top left corner of the bitMap as coordinate (0,0)) and converts it into 
the local coordinates of the current grafPort. The global point can be 
obtained with the LocalToGlobal call (see above). For example, suppose 
a game draws a ’'ball'* within a rectangle named ballRect, defined in the 
grafPort named gamePort (as illustrated below in Figure 24). If you 
want to draw that ball in the grafPort named selectPort, you can 
calculate the ball's selectPort coordinates like this: 

SetPort ( gamePort ) ; {start in origin port} 

selectBall := ballRect; {make a copy to be moved} 

LocalToGlobal(selectBall. topLef t) ; {put both corners into } 

LocalToGlobal(selectBall.botRight) ; { global coordinates } 

SetPort(selectPort) ; {switch to destination port} 

GlobalToLocal(selectBall. topLef t) ; {put both corners into } 
GlobalToLocal(selectBall.botRight) ; { these local coordinates } 
FillOval(selectBall,ballColor) ; {now you have the ball!} 
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IS 45 



Figure 24* Converting between Coordinate Systems 

You can see from Figure 24 that LocalToGlobal and GlobalToLocal simply 
offset the coordinates of the rectangle by the coordinates of the top 
left corner of the local graf Port^s boundary rectangle. You could also 
do this with OffsetRect. In fact, the way to convert regions and 
polygons from one coordinate system to another is with OffsetRgn or 
OffsetPoly rather than LocalToGlobal and GlobalToLocal. For example, 
if myRgn were a region enclosed by a rectangle having the same 
coordinates as ballRect in gamePort, you could convert the region to 
global coordinates with 

Of fsetRgn( myRgn, -20, -40); 

and then convert it to the coordinates of the selectPort grafPort with 
Of fsetRgn (myRgn, 15, -30); 


Miscellaneous Utilities 


FUNCTION Random : INTEGER; 

This function returns an integer, uniformly distributed pseudo-random, 
in the range from -32768 through 32767. The value returned depends on 
the global variable randSeed, which InitGraf initializes to 1; you can 
start the sequence over again from where it began by resetting randSeed 
to 1. 
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FUNCTION GetPixel (h,v: INTEGER) : BOOLEAN; 

GetPixel looks at the pixel associated with the given coordinate point 
and returns TRUE if it is black or FALSE if it is white. The selected 
pixel is immediately below and to the right of the point whose 
coordinates are given in h and v, in the local coordinates of the 
current grafPort. There is no guarantee that the specified pixel 
actually belongs to the port, however; it may have been drawn by a port 
overlapping the current one. To see if the point indeed belongs to the 
current port, perform a PtInRgn(pt , thePort visRgn) . 


PROCEDURE StuffHex (thingPtr: QDPtr; s: Str255); 

StuffHex pokes bits (expressed as a string of hexadecimal digits) into 
any data structure. This is a good way to create cursors, patterns, or 
bit images to be "stamped'* onto the screen with CopyBits. For example, 

Stuf fHex(@stripes , '0102040810204080') 

places a striped pattern into the pattern variable stripes. 

( eye) 

There is no range checking on the size of the destination 
variable. It's easy to overrun the variable and destroy 
something if you don't know what you're doing. 

PROCEDURE ScalePt (VAR pt : Point; srcRect ,dstRect : Rect); 

A width and height are passed in pt; the horizontal component of pt is 
the width, and the vertical component of pt is the height. ScalePt 
scales these measurements as follows and returns the result in pt : it 
multiplies the given width by the ratio of dstRect's width to srcRect s 
width, and multiplies the given height by the ratio of dstRect's height 
to srcRect's height. In Figure 25, where dstRect's width is twice 
srcRect's width and its height is three times srcRect's height, the pen 
width is scaled from 3 to 6 and the pen height is scaled from 2 to 6. 
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Figure 25. ScalePt and MapPt 


PROCEDURE MapPt (VAR pt: Point; srcRect , dstRect : Rect); 

Given a point within srcRect, MapPt maps it to a similarly located 
point within dstRect (that is, to where it would fall if it were part 
of a drawing being expanded or shrunk to fit dstRect). The result is 
returned in pt. A corner point of srcRect would be mapped to the 
corresponding corner point of dstRect, and the center of srcRect to the 
center of dstRect. In Figure 25 above, the point (3,2) in srcRect Is 
mapped to (18,7) in dstRect. FromRect and dstRect may overlap, and pt 
need not actually be within srcRect. 

( eye) 

Remember, if you are going to draw inside the rectangle 
in dstRect, you will probably also want to scale the pen 
size accordingly with ScalePt. 


PROCEDURE MapRect (VAR r: Rect; srcRect , dstRect : Rect); 

Given a rectangle within srcRect, MapRect maps it to a similarly 
located rectangle within dstRect by calling MapPt to map the top left 
and bottom right corners of the rectangle. The result is returned in 


PROCEDURE MapRgn (rgn: RgnHandle ; srcRect .dstRect : Rect); 

Given a region within srcRect, MapRgn maps it to a similarly located 

region within dstRect by calling MapPt to map all the points in the 
region. 
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PROCEDURE MapPoly (poly: PolyHandle; srcRect ,dstRect s Rect); 

Given a polygon within srcRect, MapPoly maps it to a similarly located 
polygon within dstRect by calling MapPt to map all the points that 
define the polygon. 


CUSTOMIZING QUICKDRAW OPERATIONS __ 

For each shape that QuickDraw knows how to draw, there are procedures 
that perform these basic graphic operations on the shape: frame, 
paint, erase, invert, and fill. Those procedures in turn call a 
low-level drawing routine for the shape. For example, the FrameOval, 
PaintOval, EraseOval, InvertOval, and FillOval procedures all call a 
low-level routine that draws the oval. For each type of object 
QuickDraw can draw, including text and lines, there is a pointer to 
such a routine. By changing these pointers, you can install your own 
routines, and either completely override the standard ones or call them 
after your routines have modified parameters as necessary. 

Other low-level routines that you can install in this way are: 

- The procedure that does bit transfer and is called by CopyBits. 

- The function that measures the width of text and is called by 
CharWidth, StringWidth, and TextWidth. 

- The procedure that processes picture comments and is called by 
DrawPicture. The standard such procedure ignores picture 
comments. 

- The procedure that saves drawing commands as the definition of a 
picture, and the one that retrieves them. This enables the 
application to draw on remote devices, print to the disk, get 
picture input from the disk, and support large pictures. 

The grafProcs field of a grafPort determines which low-level routines 
are called; if it contains NIL, the standard routines are called, so 
that all operations in that grafPort are done in the standard ways 
described in this manual. You can set the grafProcs field to point to 
a record of pointers to routines. The data type of grafProcs is 
QDProcsPtr : 
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{text drawing} 

{line drawing} 

{ r ect ang le dr awi ng } 

{ r oundRec t dr awi ng } 

{oval drawing} 

{arc/wedge drawing} 

{polygon drawing} 

{region drawing} 

{bit transfer} 

{picture comment processing} 
{text width measurement} 
{picture retrieval} 

{picture saving} 


To assist you in setting up a QDProcs record, QuickDraw provides the 
following procedure: 

PROCEDURE SetStdProcs (VAR procs: QDProcs); 

This procedure sets all the fields of the given QDProcs record to point 
to the standard low-level routines. You can then change the ones you 
wish to point to your own routines. For example, if your procedure 
that processes picture comments is named MyComments, you will store 
@MyComments in the commentProc field of the QDProcs record. 

The routines you install must of course have the same calling sequences 
as the standard routines, which are described below. The standard 
drawing routines tell which graphic operation to perform from a 
parameter of type Graf Verb. 

TYPE Graf Verb = (frame, paint, erase, invert, fill); 

When the grafVerb is fill, the pattern to use when filling is passed in 
the fillPat field of the grafPort. 


TYPE QDProcsPtr = "QDProcs; 

QDProcs 53 RECORD 

textProc: QDPtr 

lineProc: QDPtr 

rectProc: QDPtr 

rRectProc: QDPtr 

ovalProc: QDPtr 

arcProc: QDPtr 

polyProc: QDPtr 

rgnProc: QDPtr 

bitsProc: QDPtr 

commentProc: QDPtr 
txMeasProc: QDPtr 
getPicProc: QDPtr 
putPicProc: QDPtr 


PROCEDURE StdText (byteCount: INTEGER; textBuf: QDPtr; numer,denom: 
INTEGER) ; 

StdText is the standard low— level routine for drawing text. It draws 
text from the arbitrary structure in memory specified by textBuf, 
starting from the first byte and continuing for byteCount bytes. Numer 
and denom specify the scaling, if any: numer. v over denom.v gives the 
vertical scaling, and numer. h over denom. h gives the horizontal 
scaling. 


PROCEDURE StdLine (newPt: Point); 

StdLine is the standard low— level routine for drawing a line. It draws 
a line from the current pen location to the location specified (in 
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local coordinates) by newPt. 


PROCEDURE StdRect (verb: GrafVerb; r: Rect); 

StdRect is the standard low-level routine for drawing a rectangle. It 
draws the given rectangle according to the specified grafVerb. 


PROCEDURE StdRRect (verb: GrafVerb; r: Rect; oval width, ovalHeight : 
INTEGER) ; 

StdRRect is the standard low-level routine for drawing a rounded-corner 
rectangle. It draws the given rounded-corner rectangle according to 
the specified grafVerb. OvalWidth and ovalHeight specify the diameters 
of curvature for the corners. 


PROCEDURE StdOval (verb: GrafVerb; r: Rect); 

StdOval is the standard low-level routine for drawing an oval. It 
draws an oval inside the given rectangle according to the specified 
grafVerb. 


PROCEDURE StdArc (verb: GrafVerb; r: Rect; startAngle ,arcAngle : 

INTEGER) ; 

StdArc is the standard low-level routine for drawing an arc or a wedge. 
It draws an arc or wedge of the oval that fits inside the given 
rectangle. The grafVerb specifies the graphic operation; if it's the 
frame operation, an arc is drawn; otherwise, a wedge is drawn. 


PROCEDURE StdPoly (verb: GrafVerb; poly: PolyHandle); 

StdPoly is the standard low-level routine for drawing a polygon. It 
draws the given polygon according to the specified grafVerb. 

PROCEDURE StdRgn (verb: GrafVerb; rgn: RgnHandle); 

StdRgn is the standard low-level routine for drawing a region. It 
draws the given region according to the specified grafVerb. 


PROCEDURE StdBits (VAR srcBits: BitMap; VAR srcRect , dstRect : Rect; 
mode : INTEGER ; maskRgn : RgnHand le ) ; 

StdBits is the standard low-level routine for doing bit transfer. It 
transfers a bit image between the given bitMap and thePort portBits, 
just as if CopyBits were called with the same parameters and with a 
destination bitMap equal to thePort^. portBits. 
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PROCEDURE StdCommerit (kind,dataSize: INTEGER; dataHandle: QDHandle); 

S tdComment is the standard low-level routine for processing a picture 
comment. Kind identifies the type of comment. DataHandle is a handle 
to additional data, and dataSize is the size of that data in bytes. If 
there is no additional data for the command, dataHandle will be NIL and 
dataSize will be 0. StdComment simply ignores the comment. 


FUNCTION StdTxMeas (byteCount: INTEGER; textBuf : QDPtr; VAR 

numer,denom: Point; VAR info: Font Info) : INTEGER; 

StdTxMeas is the standard low-level routine for measuring text width. 

It returns the width of the text stored in the arbitrary structure in 
memory specified by textBuf, starting with the first byte and 
continuing for byteCount bytes. Numer and denom specify the scaling as 
in the StdText procedure; note that StdTxMeas may change them. 


PROCEDURE StdGetPic (dataPtr: QDPtr; byteCount: INTEGER); 

StdGetPic is the standard low-level routine for retrieving information 
from the definition of a picture. It retrieves the next byteCount 
bytes from the definition of the currently open picture and stores them 
in the data structure pointed to by dataPtr. 

PROCEDURE StdPutPic (dataPtr: QDPtr; byteCount: INTEGER); 

StdPutPic is the standard low-level routine for saving information as 
the definition of a picture. It saves as the definition of the 
currently open picture the drawing commands stored in the data 
structure pointed to by dataPtr, starting with the first byte and 
continuing for the next byteCount bytes. 


USING QUICKDRAW FROM ASSEMBLY LANGUAGE 

All Macintosh User Interface Toolbox routines can be called from 
assembly-language programs as well as from Pascal. When you write an 
assembly— language program to use these routines, though, you must 
emulate Pascal's parameter passing and variable transfer protocols. 

This section discusses how to use the QuickDraw constants, global 
variables, data types, procedures, and functions from assembly 
language . 

The primary aid to assembly-language programmers is a file named 
GRAFTYPE S . TE XT . If you use .INCLUDE to include this file when you 
assemble your program, all the QuickDraw constants, offsets to 
locations of global variables, and offsets into the fields of 
structured types will be available in symbolic form. 
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Constants _ — — 

QuickDraw constants are stored in the GRAFTYPES.TEXT file, ^and you can 
use the constant values symbolically. For example, if you ve loaded 
the effective address of the thePort'. txMode field into address 
register A2, you can set that field to the srcXor mode with this 

statement : 

MOVE.W //SRCXOR, (A2) 

To refer to the number of bytes occupied by the QuickDraw global 
variables, you can use the constant GRAFSIZE. When you call the 
InitGraf procedure, you must pass a pointer to an area at least t at 

large. 


Data Types — 

Pascal's strong typing ability lets you write Pascal programs without 
really considering the size of a variable. But in assembly language, 
you must keep track of the size of every variable. The sizes of the 
standard Pascal data types are as follows: 


Type Size 

INTEGER Word (2 bytes) 

T^onglnt Long (4 bytes) 

BOOLEAN Word (2 bytes) 

CHAR Word (2 bytes) 

REAL Long (4 bytes) 

INTEGERS and Longlnts are in two's complement form; BOOLEANs have their 
boolean value in bit 8 of the word (the low-order bit of the byte at 
the same location); CHARs are stored in the high-order byte of the 
word; and REALS are in the KCS standard format. 

The QuickDraw simple data types listed below are constructed out of 
these fundamental types. 


Type 

QDPtr 

QDHandle 

Word 

Str255 

Pattern 

Bitsl6 


Size 

Long (4 bytes) 
Long (4 bytes) 
Long (4 bytes) 
Page (256 bytes) 
8 bytes 
32 bytes 


Other data types are constructed as records of variables of the above 
types. The size of such a type is the sum of the sizes of all the 
fields in the record; the fields appear in the variable with the first 
field in the lowest address. For example, consider the data type 
BitMap, which is defined like this: 
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TYPE BitMap » RECORD 

baseAddr: QDPtr; 
rowBytes: INTEGER; 
bounds: Rect 

END; 

This data type would be arranged in memory as seven words: a long for 
the baseAddr, a word for the rowBytes, and four words for the top, 
left, right, and bottom parts of the bounds rectangle. To assist you 
in referring to the fields inside a variable that has a structure like 
this, the GRAFTYPES.TEXT file defines constants that you can use as 
offsets into the fields of a structured variable. For example, to move 
a bitMap's rowBytes value into D3, you would execute the following 
instruction: 

MOVE . W MYBITMAP+ROWBYTES , D3 

Displacements are given in the GRAFTYPES.TEXT file for all fields of 
all data types defined by QuickDraw. 

To do double indirection, you perform an LEA indirectly to obtain the 
effective address from the handle. For example, to get at the top 
coordinate of a region's enclosing rectangle: 

MOVE.L MYHANDLE,A1 ; Load handle into A1 

MOVE.L (A1),A1 ; Use handle to get pointer 

MOVE.W RGNBBOX-KTOP(Al) ,D3 ; Load value using pointer 

( eye) 

For regions (and all other variable-length structures 
with handles), you must not move the pointer into a 
register once and just continue to use that pointer; you 
must do the double indirection each time. Every 
QuickDraw, Toolbox, or memory management call you make 
can possibly trigger a heap compaction that renders all 
pointers to movable heap items (like regions) invalid. 

The handles will remain valid, but pointers you've 
obtained through handles can be rendered invalid at any 
subroutine call or trap in your program. 


Global Variables 


Global variables are stored in a special section of Macintosh low 
memory; register A5 always points to this section of memory. The 
GRAFTYPES.TEXT file defines a constant GRAFGLOB that points to the 
beginning of the QuickDraw variables in this space, and other constants 
that point to the individual variables. To access one of the 
variables, put GRAFGLOB in an address register, sum the constants, and 
index off of that register. For example, if you want to know the 
horizontal coordinate of the pen location for the current grafPort, 
which the global variable thePort points to, you can give the following 
instructions : 
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MO VE . L GRAF GLOB ( A5 ) , A0 
MO VE . L THEPORT ( A0 ) , Al 
MOVE.W PNLOC+H ( Al ) , D0 


Point to QuickDraw globals 
Get current grafPort 
Ge t thePo r t ~ . pnLo c . h 


Procedures and Functions — 

To call a QuickDraw procedure or function, you must push all parameters 
to it on the stack, then JSR to the function or procedure. When you 
link your program with QuickDraw, these JSRs are adjusted to refer to 
the jump table in low RAM, so that a JSR into the table redirects you 
to the actual location of the procedure or function. 

The only difficult part about calling QuickDraw procedures and 
functions is stacking the parameters. You must follow some strict 
rules : 

- Save all registers you wish to preserve BEFORE you begin pushing 
parameters. Any QuickDraw procedure or function can destroy the 
contents of the registers A0, Al, D0, Dl , and D2, but the others 
are never altered. 

- Push the parameters in the order that they appear in the Pascal 
procedural interface. 

- For booleans, push a byte; for integers and characters, push a 
word; for pointers, handles, long integers, and reals, push a 
long. 

- For any structured variable longer than four (4) bytes, push a 
pointer to the variable. 

- For all VAR parameters, regardless of size, push a pointer to the 
variable. 

- When calling a function, FIRST push a null entry equal to the size 
of the function result, THEN push all other parameters. The 
result will be left on the stack after the function returns to 
you. 

This makes for a lengthy interface, but it also guarantees that you can 
mock up a Pascal version of your program, and later translate it into 
assembly code that works the same. For example, the Pascal statement 

blackness := GetPixel(50,mousePos.v) ; 


would be written in assembly language 

CLR.W -(SP) 

MOVE.W #50, -(SP) 

MOVE.W MOUSEPOS+V , - ( SP ) 

JSR GETPIXEL 
MOVE.W (SP)+, BLACKNESS 


like this: 

; Save space for boolean result 
; Push constant 50 (decimal) 

; Push the value of mousePos.v 
; Call routine 
: Fetch result from stack 
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This is a simple example, pushing and pulling word-long constants- 
Normally, you'11 he pushing more pointers, using the PEA (Push 
Effective Address) instruction* 

FillRoundRect (myRect , 1 , thePort ~ . pnSize . v ,whi te) ; 


PEA 

MYRECT 

MOVE. W 

#1,-(SP) 

MOVE.L 

GRAFGL0B(A5) ,A0 

MOVE.L 

THEPORT(A0),A1 

MOVE. W 

PNSIZE+V(A1),-(SP) 

PEA 

WHITE (A0) 

JSR 

FILLROUNDRECT 


Push pointer to myRect 

Push constant 1 

Point to QuickDraw globals 

Get current grafPort 

Push value of thePort pnSize .v 

Push pointer to global variable white 

Call the subroutine 


To call the TextFace procedure, push a word in which each of seven bits 
represents a stylistic variation: set bit 0 for bold, bit 1 for 
italic, bit 2 for underline, bit 3 for outline, bit 4 for shadow, bit 5 
for condense, and bit 6 for extend- 
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SUMMARY OF QUICKDRAW 


CONST srcCopy = 0; 
srcOr = 1; 

srcXor = 2; 
srcBic = 3; 
notSrcCopy = 4; 
notSrcOr = 5; 
notSrcXor = 6; 
notSrcBic = 7; 
patCopy = 8; 
patOr = 9; 

patXor = 10; 
patBic = 11; 
notPatCopy * 12; 
notPatOr - 13; 
notPatXor =14; 

notPatBic =15; ^ 

blackColor = 33; 

whiteColor = 30; 

redColor = 205; 

greenColor = 341; 

blueColor = 409; 

cyanColor = 273; 


magentaColor = 137 ; 
yellowColor = 69; 

picLParen = 0; 
picRParen = 1; 

TYPE QDByte = -128.. 127; 

QDPtr = "QDByte; 

QDHandle = "QDPtr; 

Str255 = STRING [255] ; 

Pattern = PACKED ARRAY [0. .7] OF 0..255; 

Bitsl6 = ARRAY [0..15] OF INTEGER; ^ 

Graf Verb = (frame, paint, erase, invert, fill); 

Styleltem = (bold, italic, underline, outline, shadow, condense, 
extend) ; 

Style = SET OF Styleltem; 

Fontlnfo = RECORD 

ascent: INTEGER; 

descent: INTEGER; 
widMax: INTEGER; 

leading: INTEGER 
END; 
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VHSelect » (v,h); 

Point * RECORD CASE INTEGER OF 

0 s (vs INTEGER; 
h: INTEGER); 

Is (vh: ARRAY [VHSelect] OF INTEGER) 
END; 

Rect = RECORD CASE INTEGER OF 

0: (tops INTEGER; 

left: INTEGER; 

bottoms INTEGER; 
right: INTEGER); 

Is (topLeft: Point; 
botRight: Point) 

END; 

BitMap « RECORD 

baseAddr: QDPtr; 
rowByt es s INTEGER ; 
bounds: Rect 

END; 

Cursor = RECORD 

data: Bitsl6; 

mask: Bitsl6; 

hotSpot: Point 
END; 

PenS tat e = RECORD 

pnLoc: Point; 

pnSize: Point; 

pnMode : INTEGER ; 

pnPat: Pattern 

END; 

RgnHandle = ~RgnPtr; 

RgnPtr = ^Region; 

Region = RECORD 

rgnSize: INTEGER; 

rgnBBox: Rect; 

{more data if not rectangular} 
END; 
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PicHandle = 'PicPtr ; 

PicPtr = 'Picture; 

Picture ■ RECORD 

picSize: INTEGER; 

picFrame: Rect ; 

{picture definition data} 
END; 


PolyHandle = 'PolyPtr; 

PolyPtr = 'Polygon; 

Polygon = RECORD 

polySize: INTEGER; 

polyBBox: Rect; 

polyPoints: ARRAY [0..0] OF Point 
END; 

QDProcsPtr = 'QDProcs ; 

QDProcs = RECORD 


textProc: 

QDPtr ; 

lineProc: 

QDPtr ; 

rectProc: 

QDPtr ; 

rRectProc: 

QDPtr ; 

ovalProc: 

QDPtr ; 

arcProc: 

QDPtr ; 

polyProc: 

QDPtr ; 

rgnProc : 

QDPtr ; 

bitsProc: 

QDPtr ; 

commentProc: 

QDPtr; 

txMeasProc: 

QDPtr ; 

getPicProc: 

QDPtr ; 

putPicProc: 

QDPtr 


END; 
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G rafPtr ■ "GrafPort; 
GrafPort - RECORD 


levice : 

INTEGER; 

portBits : 

BitMap ; 

portRect : 

Rect ; 

visRgn: 

RgnHand le ; 

clipRgn: 

RgnHandle ; 

bkPat : 

Pattern; 

fillPat: 

Pattern; 

pnLoc: 

Point; 

pnSize: 

Point; 

pnMode: 

INTEGER; 

pnPat : 

Pattern; 

pnVis : 

INTEGER; 

txFont : 

INTEGER; 

txFace: 

Style; 

txMode : 

INTEGER; 

txSize : 

INTEGER ; 

spExtra: 

INTEGER; 

fgColor: 

Longlnt ; 

bkColor: 

Longlnt ; 

colrBit : 

INTEGER; 

patStretch: 

INTEGER; 

picSave: 

QDHandle ; 

rgnSave: 

QDHand le ; 

poly Save : 

QDHandle ; 

grafProcs : 

QDProcsPtr 


END; 


VAR thePort: 
white: 
black: 
gray: 
ltGray : 
dkGray : 
arrow: 
screenBits: 
randSeed : 


Graf Ptr ; 

Pattern; 

Pattern; 

Pattern; 

Pattern; 

Pattern; 

Cursor; 

BitMap ; 

Longlnt ; 


GrafPort Routines 


PROCEDURE InitGraf 
PROCEDURE OpenPort 
PROCEDURE InitPort 
PROCEDURE ClosePort 
PROCEDURE SetPort 
PROCEDURE GetPort 
PROCEDURE Graf Device 
PROCEDURE SetPortBits 
PROCEDURE PortSize 
PROCEDURE MovePortTo 
PROCEDURE SetOrigin 


( globalP tr : QDPtr ) ; 

(gp: Graf Ptr); 

(gp: Graf Ptr); 

(gp: GrafPtr); 

(gp: GrafPtr); 

(VAR gp: GrafPtr); 
(device: INTEGER); 

(bm: BitMap); 

(width, height: INTEGER) 
( lef tGlobal , topGlobal : 
(h, v: INTEGER); 
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PROCEDURE SetClip 
PROCEDURE GetClip 
PROCEDURE ClipRect 
PROCEDURE BackPat 


(rgn: RgnHandle) ; 
( rgn : RgnHand le ) ; 
(r: Rect); 

(pat: Pattern); 


Cursor Handling 

PROCEDURE InitCursor; 

PROCEDURE SetCursor (crsr: Cursor); 

PROCEDURE HideCursor; 

PROCEDURE ShowCursor; 

PROCEDURE ObscureCursor ; 


Pen and Line Drawing 


PROCEDURE HidePen; 
PROCEDURE ShowPen; 
PROCEDURE GetPen 
PROCEDURE GetPenState 
PROCEDURE SetPenState 
PROCEDURE PenSize 
PROCEDURE PenMode 
PROCEDURE PenPat 
PROCEDURE PenNormal ; 
PROCEDURE MoveTo 
PROCEDURE Move 
PROCEDURE LineTo 
PROCEDURE Line 


(VAR pt: Point); 

(VAR pnState: PenState) 
(pnState: PenState); 
(width, height: INTEGER) 
(mode: INTEGER); 

(pat: Pattern); 

(h,v: INTEGER); 

(dh,dv: INTEGER); 

(h,v: INTEGER); 

(dh,dv: INTEGER); 


Text Drawing 


PROCEDURE TextFont 
PROCEDURE TextFace 
PROCEDURE TextMode 
PROCEDURE TextSize 
PROCEDURE SpaceExtra 
PROCEDURE DrawChar 
PROCEDURE DrawString 
PROCEDURE DrawText 
FUNCTION CharWidth 
FUNCTION StringWidth 
FUNCTION TextWidth 

PROCEDURE GetFontlnfo 


(font: INTEGER); 

(face: Style); 

(mode: INTEGER); 

(size: INTEGER); 

(extra: INTEGER); 

(ch: CHAR); 

(s: Str255); 

(textBuf: QDPtr; f irstByte.byteCount : 
(ch: CHAR) : INTEGER; 

(s: Str255) : INTEGER; 

(textBuf: QDPtr; firstByte.byteCount : 
INTEGER; 

(VAR info: Fontlnfo); 


INTEGER) ; 
INTEGER) : 
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Drawing in Color 

PROCEDURE ForeColor (color: Longlnt); 
PROCEDURE BackColor (color: Longlnt); 
PROCEDURE ColorBit (whichBit: INTEGER); 




Calculations with Rectangles 


PROCEDURE 

PROCEDURE 

PROCEDURE 

FUNCTION 

PROCEDURE 

FUNCTION 

PROCEDURE 

PROCEDURE 

FUNCTION 

FUNCTION 


SetRect 
Of fsetRect 
InsetRect 
SectRect 

UnionRect 

PtlnRect 

Pt2Rect 

PtToAngle 

EqualRect 

EmptyRect 


(VAR r: Rect ; left, top, right, bottom: INTEGER); 
(VAR r: Rect; dh,dv: INTEGER); 

(VAR r: Rect; dh,dv: INTEGER); 

(srcRectA, srcRectB: Rect; VAR dstRect: Rect) : 
BOOLEAN; 

(srcRectA, srcRectB: Rect; VAR dstRect: Rect) 
(pt: Point; r: Rect) : BOOLEAN; 

(ptA,ptB: Point; VAR dstRect: Rect); 

(r: Rect; pt: Point; VAR angle: INTEGER); 
(rectA, rectB: Rect) : BOOLEAN; 

(r: Rect) : BOOLEAN; 


Graphic Operations on Rectangles 

PROCEDURE FrameRect (r: Rect); 

PROCEDURE PaintRect (r: Rect); 

PROCEDURE EraseRect (r: Rect); 

PROCEDURE InvertRect (r: Rect); 

PROCEDURE FillRect (r: Rect; pat: Pattern); 


Graphic Operations on Ovals 


PROCEDURE FrameOval (r: Rect); 

PROCEDURE PaintOval (r: Rect); 

PROCEDURE EraseOval (r: Rect); 

PROCEDURE InvertOval (r: Rect); 

PROCEDURE FillOval (r: Rect; pat: Pattern); 


Graphic Operations on Rounded-Corner Rectangles 


PROCEDURE FrameRoundRect 
PROCEDURE PaintRoundRect 
PROCEDURE EraseRoundRect 
PROCEDURE InvertRoundRect 
PROCEDURE FillRoundRect 


(r: Rect; ovalWidth,ovalHeight : 
(r: Rect; ovalWidth,ovalHeight : 
(r: Rect; ovalWidth,ovalHeight : 
(r: Rect; ovalWidth,ovalHeight : 
(r: Rect; ovalWidth,ovalHeight : 
pat: Pattern); 


INTEGER) ; 
INTEGER) ; 
INTEGER) ; 
INTEGER) ; 
INTEGER; 


Z 0 ^ 
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Graphic Operations on Arcs and Wedges 


PROCEDURE FrameArc (r: Rect; startAngle ,arcAngle : INTEGER); 
PROCEDURE PaintArc (r: Rect; startAngle ,arcAngle : INTEGER); 
PROCEDURE EraseArc (r: Rect; startAngle ,arcAngle : INTEGER); 
PROCEDURE InvertArc (r: Rect; startAngle ,arcAngle : INTEGER); 
PROCEDURE FillArc (r: Rect; startAngle ,arcAngle : INTEGER; pat: 

Pattern) ; 


Calculations with Regions 


FUNCTION 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

FUNCTION 

FUNCTION 

FUNCTION 

FUNCTION 


NewRgn : RgnHandle; 

DisposeRgn (rgn: RgnHandle); 

CopyRgn (srcRgn, dstRgn: RgnHandle); 

SetEmptyRgn (rgn: RgnHandle); 

SetRectRgn (rgn: RgnHandle; left, top, right, bottom: 
RectRgn (rgn: RgnHandle; r: Rect); 

OpenRgn ; 

CloseRgn (dstRgn: RgnHandle); 

OffsetRgn (rgn: RgnHandle; dh,dv: INTEGER); 
InsetRgn (rgn: RgnHandle; dh,dv: INTEGER); 
SectRgn (srcRgnA, srcRgnB, dstRgn: RgnHandle) ; 

UnionRgn (srcRgnA, srcRgnB, dstRgn: RgnHandle) ; 

DiffRgn (srcRgnA, srcRgnB, dstRgn: RgnHandle) ; 

XbrRgn (srcRgnA, srcRgnB, dstRgn: RgnHandle) ; 

PtlnRgn (pt: Point; rgn: RgnHandle) : BOOLEAN; 
RectlnRgn (r: Rect; rgn: RgnHandle) : BOOLEAN; 

EqualRgn (rgnA,rgnB: RgnHandle) : BOOLEAN; 

EmptyRgn (rgn: RgnHandle) : BOOLEAN; 


INTEGER) ; 




Graphic Operations on Regions 

PROCEDURE FrameRgn (rgn: RgnHandle); 

PROCEDURE PaintRgn (rgn: RgnHandle); 

PROCEDURE EraseRgn (rgn: RgnHandle); 

PROCEDURE Inver tRgn (rgn: RgnHandle); 

PROCEDURE FillRgn (rgn: RgnHandle; pat: Pattern); 


Bit Transfer Operations 


PROCEDURE ScrollRect (r: Rect; dh,dv: INTEGER; updateRgn: RgnHandle); 
PROCEDURE CopyBits (srcBits, dstBits : BitMap; srcRect ,dstRect : Rect; 

mode: INTEGER; maskRgn: RgnHandle); 
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Pictures 


FUNCTION OpenPicture (picFrame: Rect) : PicHandle; 

PROCEDURE PicComment (kind .dataSize: INTEGER; dataHandle: QDHandle); 
PROCEDURE ClosePicture ; 

PROCEDURE DrawPicture (myPicture: PicHandle; dstRect: Rect); 

PROCEDURE KillPicture (myPicture: PicHandle); 


Calculations with Polygons 

FUNCTION OpenPoly : PolyHandle; 

PROCEDURE ClosePoly; 

PROCEDURE KillPoly (poly: PolyHandle); 

PROCEDURE OffsetPoly (poly: PolyHandle; dh,dv: INTEGER); 


Graphic Operations on Polygons 

PROCEDURE FramePoly (poly: PolyHandle); 

PROCEDURE PaintPoly (poly: PolyHandle); 

PROCEDURE ErasePoly (poly: PolyHandle); 

PROCEDURE TnvertPoly (poly: PolyHandle); 

PROCEDURE FillPoly (poly: PolyHandle; pat: Pattern); 


Calculations with Points 


PROCEDURE AddPt 
PROCEDURE SubPt 
PROCEDURE SetPt 
FUNCTION EqualPt 
PROCEDURE LocalToGlobal 
PROCEDURE GlobalToLocal 


(srcPt: Point; VAR dstPt: Point); 
(srcPt: Point; VAR dstPt: Point); 
(VAR pt: Point; h,v: INTEGER); 
(ptA.ptB: Point) : BOOLEAN; 

(VAR pt: Point); 

(VAR pt: Point); 


Miscellaneous Utilities 


FUNCTION 

FUNCTION 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 

PROCEDURE 


Random : INTEGER; 

GetPixel (h,v: INTEGER) : BOOLEAN; 

StuffHex (thingPtr: QDPtr; s: Str255); 

ScalePt (VAR pt: Point; srcRect , dstRect : Rect); 
MapPt (VAR pt: Point; srcRect , dstRect : Rect); 

MapRect (VAR r: Rect; srcRect .dstRect : Rect); 
MapRgn (rgn: RgnHandle; srcRect .dstRect : Rect); 
MapPoly (poly: PolyHandle; srcRect .dstRect : Rect); 
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Customizing QuickDraw Operations 


PROCEDURE SetStdProcs (VAR procs: QDPr°« ) 5 QDPt numer ,denom: 

PROCEDURE StdText (byteCount. INTEGER, textAa ^ 

Point') : 


PROCEDURE StdLine 
PROCEDURE StdRect 
PROCEDURE StdRRect 

PROCEDURE StdOval 
PROCEDURE StdArc 

PROCEDURE StdPoly 
PROCEDURE StdRgn 
PROCEDURE StdBits 

PROCEDURE StdComment 
FUNCTION StdTxMeas 

PROCEDURE StdGetPic 
PROCEDURE StdPutPic 


(newPt: Point); 

(verb: Graf Verb; r: Rect); . 

(verb: GrafVerb; r: Rect; ovalwidth.ovalHeight : 

INTEGER) ; 

(verb: GrafVerb; r: Rect); 

(verb: GrafVerb; r: Rect; startAngle.arcAngle: 
INTEGER) ; 

(verb: GrafVerb; poly: PolyHandle); 

(verb: GrafVerb; rgn: RgnHandle); 

(VAR srcBits : BitMap; VAR srcRect , dstRect : Rect; 
mode: INTEGER; maskRgn: RgnHandle); 

(kind .dataSize : INTEGER; dataHandle: QDHandle); 
(byteCount: INTEGER; textBuf: QDPtr; VAR numer, 
denom: Point; VAR info: Fontlnfo) : INTEGER; 
(dataPtr: QDPtr; byteCount: INTEGER); 

(dataPtr : QDPtr; byteCount: INTEGER); 
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bit image: A collection of bits in memory which have a rectilinear 
representation. The Macintosh screen is a visible bit image. 

bitMap: A pointer to a bit image, the row width of that image, and its 

boundary rectangle. 

boundary rectangle: A rectangle defined as part of a bitMap, which 
encloses the active area of the bit image and imposes a coordinate 
system on it. Its top left corner is always aligned around the first 
bit in the bit image. 

character style: A set of stylistic variations, such as bold, italic, 
and underline. The empty set indicates normal text (no stylistic 
variations). 

clipping: Limiting drawing to within the bounds of a particular area, 
clipping region: Same as clipRgn. 

clipRgn: The region to which an application limits drawing in a 

graf Port . 

coordinate plane: A two-dimensional grid. In QuickDraw, the grid 
coordinated are integers ranging from -32768 to +32767, and all grid 
lines are infinitely thin. 

cursor: A 16-by-16-bit image that appears on the screen and is 
controlled by the mouse; called the "pointer” in other Macintosh 
documentation. 

cursor level: A value, initialized to 0 when the system is booted, 
that keeps track of the number of times the cursor has been hidden. 

empty: Containing no bits, as a shape defined by only one point. 

font: The complete set of characters of one typeface, such as 
Helvetica. 

frame: To draw a shape by drawing an outline of it. 

global coordinate system: The coordinate system based on the top left 
corner of the bit image being at (0,0). 

grafPort: A complete drawing environment, including such elements as a 
bitMap, a subset of it in which to draw, a character font, patterns for 
drawing and erasing, and other pen characteristics. 

grafPtr: A pointer to a grafPort. 

handle: A pointer to one master pointer to a dynamic, relocatable data 
structure (such as a region). 
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hotspot: The point in a cursor that is aligned with the mouse 

position. 

kern: To stretch part of a character back under the previous 

character. 

local coordinate system: The coordinate system local to a grafPort, 
imposed by the boundary rectangle defined in its bitMap. 

missing symbol: A character to be drawn in case of a request to draw a 
character that is missing from a particular font. 

pattern: An 8-by-8-bit image, used to define a repeating design (such 

as stripes) or tone (such as gray). 

pattern transfer mode: One of eight transfer modes for drawing lines 
or shapes with a pattern. 

picture: A saved sequence of QuickDraw drawing commands (and, 

optionally, picture comments) that you can play back later with a 
single procedure call; also, the image resulting from these commands. 

picture comments: Data stored in the definition of a picture which 
does not affect the picture's appearance but may be used to provide 
additional information about the picture when it's played back. 

picture frame: A rectangle, defined as part of a picture, which 
surrounds the picture and gives a frame of reference for scaling when 
the picture is drawn. 

pixel: The visual representation of a bit on the screen (white if the 

bit is 0, black if it's 1). 

point: The intersection of a horizontal grid line and a vertical grid 

line on the coordinate plane, defined by a horizontal and a vertical 
coordinate. 

polygon: A sequence of connected lines, defined by QuickDraw 

line-drawing commands. 

port: Same as grafPort. 

port Bits: The bitMap of a grafPort. 

portBits. bounds: The boundary rectangle of a grafPort's bitMap. 

portRect: A rectangle, defined as part of a grafPort, which encloses a 

subset of the bitMap for use by the grafPort. 

region: An arbitrary area or set of areas on the coordinate plane. 

The outline of a region should be one or more closed loops. 

row width: The number of bytes in each row of a bit image. 
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solid: Filled in with any pattern. 

source transfer mode: One of eight transfer modes for drawing text or 
transferring any bit image between two bitMaps. 

style: See character style. 

thePort: A global variable that points to the current grafPort. 

transfer mode: A specification of which boolean operation QuickDraw 
should perform when drawing or when transferring a bit image from one 
bitMap to another. 

visRgn: The region of a grafPort, manipulated by the Window Manager, 

which is actually visible on the screen. 
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The Resource Compiler Input File 

To create your applications resource file, you^ll need to prepare your 
own input file to the Resource Compiler (Work: SampResDef • Text) . One of 
the entries in the input file specifies the name to be given to the 
resulting resource file (Mac: Samp* Rsrc) • Another entry specifies the 
Linker output file (Work:LSamp.Obj) as the file from which the 
application code segments are to be read. (As discussed in the 
Resource Manager manual, these segments are actually resources of the 
application.) Other entries may specify files from which additional 
resources are to be read; those files should also be on your 
Work: volume. 

If you don' t want to include any resources other than the code 
segments, you can have a simple input file like this: 

* SampResDef — Resource input for sample application 

* Written by Macintosh User Education 

Mac: Samp.Rsrc 

Type CODE 
LSamp ,0 

The format of an input file to the Resource Compiler is described in 
detail below. You may find it helpful to look at the input file for 
the system resources, Rsrc: SysResDef .Text , as a model. 
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It's a good idea to begin the input file with a comment that describes 
its contents and gives its author or other such information. Any line 
beginning with an asterisk (*) is treated as a comment (that is, 
ignored) . Blank lines and leading spaces are also ignored in the input 
file, and embedded spaces are ignored except in file names, titles, or 
other text strings*. 

The first line that isn't a comment must specify the name to be given 
to the resulting resource file* This should be the name of the 
application followed by ”.Rsrc", and it should be on the Mac: volume. 

Then, for each type of resource to be defined, there s one or more 
’’Type statements”. A Type statement consists of the word Type 
followed by the resource type (without quotes) and, below that, an 
entry of the following format for each resource: 

file name/ resource name , resource ID (resource attributes) 
type- specific data 

You must always provide a resource ID. Don't use ID numbers that 
conflict with those in the system resource file unless you want to 
override those resources. The documentation about a particular type of 
resource will tell you what range of resource IDs is reserved for 
system resources of that type* You can also look in 
Rsrc : SysResDef .Text to see exactly which IDs are currently in use in 
the system resource file* 

Specifications other than the resource ID may or may not be required, 
depending on the resource type. 

- Either there will be some type-specific data defining the resource 
or you'll give a file name indicating where the resource will be 
read from. You can specify a volume; if not, the prefix volume 
will be assumed. Even in the absence of a file name, you MUST 
include the comma before the resource ID. 

- You specify a resource name along with the file name for fonts and 
drivers only. The Menu Manager routines AddResMenu and 
InsertResMenu will put these resource names in menus. Enter the 
names in the combination of uppercase and lowercase that you want 
to appear in the menus. 

- Resource attributes in parentheses are optional for all types. 
They're given as a number equal to the value of the resource 
attributes byte, and (3 is assumed if none is specified. (See the 
Resource Manager manual for details.) For example, for a resource 
that's purgeable but has no other attributes set, the input will 
be "(3 2)"; for one that's purgeable and in the system heap, it 
will be "(96)" . 

The formats for the different types of resources are best explained by 
example. An example of each type of resource is given below along with 
comments that provide further explanation. Here are some points to 
remember : 
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- In every case, resource attributes in parentheses may be specified 
after the resource ID. 

- All numbers are base 10 except where hexadecimal is indicated. 

- The Type statements may appear in any order in the input file. 


( hand) 

The types "MBAR", "PICT" , and "PACK" are currently not 
recognized by the Resource Compiler. 


Type WIND 

,1 

Status Report 
40 80 120 300 
Visible GoAway 
0 
0 


Window template 
Resource ID 
Window title 
BoundsRect 

For FALSE: Invisible or NoGoAway 
ProcID (window definition iD) 
RefCon (reference value) 


Type WDEF 
WindFunc,9 


Window definition function 
File name , resource ID 


Type MENU 

9 

> *- 

Edit 
Cut/X 
Copy/C 
Pas te/Z 
( 

Show Scrap 


Menu (standard, enabled) 

Resource ID 
Menu title 

Menu items, with meta-characters 
(except M ; M for item separation 
and ”<" for character style) 
Space required after this "(" to 
designate blank line 


Type MDEF 
MenuProc, 12 


Menu definition procedure 
File name , resource ID 


Type CNTL 

,1 

Help 

55 20 75 90 
Visible 

0 

1 

0 0 0 


Control template 
Resource ID 
Control title 
BoundsRect 

For FALSE: Invisible 
ProcID (control definition ID) 
RefCon (reference value) 

Value minimum maximum 


Type CDEF 
CntlFunc,9 


Control definition function 
File name , resource ID 


Type DLOG 

,1 

100 100 190 250 
Visible 1 GoAway 0 
3 


Dialog template 
Resource ID 
BoundsRect 

1 is procID, 0 is refCon 
Resource ID of item list 
Title (none in this case) 
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Type ALRT 

,1 

120 100 190 250 
5 

F721 


Alert template 
Resource ID 
BoundsRect 

Resource ID of item list 
Stages word in hexadecimal 


Type DITL 
,3 
5 

Btnltem Enabled 
60 10 80 70 
Start 

ResCItem Enabled 
60 30 80 100 
1 


Item list in dialog or alert 

Resource ID 

Number of items 

Also: Chkltem, Radioitem 

Display rectangle 

Title 

Blank line required between items 
Control defined in control template 
Display rectangle 
Resource ID of control template 


StatText Disabled 
10 93 26 130 
Seed 


Also: EditText 
Display rectangle 

The text (may be blank if EditText) 


Iconltem Disabled 
10 24 42 56 
1 


Also: Picltem 

Display rectangle 
Resource ID of icon 


Userltem Disabled 
20 50 60 85 


Application-defined item 
Display rectangle 


Type ICON 

,1 

0380 0000 
• • • 
1EC0 3180 


Icon 

Resource ID 

The icon in hexadecimal (32 such 
lines altogether; embedded spaces 
ignored) 


Type FONT 

Grif fin/ Griff in, 38400 
Griffinl0, 38410 
Griffinl2, 38412 

Type CURS 
,300 

7FFC . . . 287F 
0FC0 . . . 1FF8 
0008 0008 


Font (or FWID for font widths) 

File name/resource name, resource ID 
File name, resource ID (size 10) 

File name , resource ID (size 12) 

[ SEE NOTE BELOW ABOUT FONTS ] 

Cursor 

Resource ID 

The data: 64 hex digits altogether 
The mask: 64 hex digits altogether 
The hotSpot point in hexadecimal 


Type PAT 

,200 

AADDAA6 6 AADDAA6 6 


Pattern 
Resource ID 

The pattern in hexadecimal 


Type PAT# 

,25 

2 

5522552255225522 

FFEEDDCCFFEEDDCC 


Pattern list 

Resource ID 

Number of patterns 

The patterns in hexadecimal 

(one per line) 
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Type SIR 
,36 

This is your string 


String 
Resource ID 

The string (one line only) 


Type DRVR 

Monkey/Monkey , 200 


Desk accessory or other I/O driver 
File name/ resource name , resource ID 


Type KEYC 
MyKey , 38 


Keyboard configuration 
File name, resource ID 


Type ANYB 
MyData,7 
36,256 


Any bytes 

File name .resource ID 

Number of bytes, off set in file 


Type CODE 
LSamp ,0 


Application code segments 

Linker output file name , resource ID 

(".Obj" is assumed.) 


Notice that three font resources are listed above, having resource IDs 
38400, 384 10 , and 38412. The resource ID for a given font number and 
size is 128 times the font number plus the size, and size 0 is use 
provide only the name of the font. Thus the font number for the 
resource illustrated here is 300, its file name and resource name are 
Griffin, and it's defined in two sizes, 10 and 12. 

If you're going to write to the resulting resource file as well as read 
it, you should place the Type statement for the application co e 
segments at the end of the input file, as shown above. In general, any 
resources you might change and write out to the resource file should be 
listed first in the input file, and any resources you won t change 
(like the code segments) should be listed last. The reason 0 , 

that the Resource Compiler stores resources in the reverse of J 
that they're listed, and it's more efficient for the esource i 
to do file compaction if the changed resources ar6 at the end of 
resource file. 






The Master Exec File 


The master Exec file (WorktNewSamp .Text) will be as h U 

requires that your prefix be set to Work.: and tha 
diskette be in disk drive 2. 
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ABSTRACT 

The data that defines menus, fonts, and other such resources used by a 
Mac :lnt replication is stored separately in a resource file* The 
Resource Manager is called by other units of the Macintosh User 
interface Toolbox, and sometimes directly by an application, to access 
resource files . It's also the tool to use when writing a program to 
create or edit resource files* This manual describes resource files and 
the Resource Manager routines* 


Summary of significant changes and additions since last version: 

The following have been updated: the list of standard resource 
types (page 8); the discussion of resource attributes (page 10): 
and the discussion of resources within resources (page 12). 

~ GpenBesFile and CloseResFi le have changed (page 1.6)* 

- CbangedResData has been renamed ChangedResouree; its description 
and the descriptions of most other routines for modifying 
resources (page. 22) have changed* 

The following routines have been added: RsrcZoneIn.it (page 15); 
CreateResFiie (page 15); CurResFile (page 16); DetachResource 
(page 19); WriteResource (page 24); and SetResPurge (page 24) * 

•" The format of a resource file has changed (page 25). 
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ABOUT THIS MANUAL 


This manual describes the Resource Manager of the Macintosh User 
Interface Toolbox and discusses resource files, which are created and 
accessed with the aid of the Resource Manager. Resource files contain 
certain types of data used by a Macintosh application, such as menus 
and fonts; the data is stored separately from the application code for 
flexibility and ease of maintenance. 

- You can use an existing program for creating and editing resource 
files (such as the Resource Editor), or write one of your own. 
These programs will call Resource Manager routines. *** There's 
currently no Resource Editor, but there's an interim Resource 
Compiler that will create resource files for certain types of 
resources; for more information, see your Macintosh software 
coordinator. *** 

- When you call routines in other Toolbox units that access 
resources, they will call the Resource Manager. In this case, you 
may need to call a Resource Manager file-opening routine, and 
possibly other routines to access the resource file directly if 
desired. 

( hand) 

This manual describes version 4 of the ROM. If you are 
using a different version, the Resource Manager and the 
file system may not work as discussed here. 

Like all documentation about Toolbox units, this manual assumes you're 
familiar with the Macintosh User Interface Guidelines, Lisa Pascal, and 
the Macintosh Operating System's Memory Manager. You should also be 
familiar with the following: 

- The Finder, at least in general. Resource files help the Finder 
perform some of its basic functions. 

- The Macintosh file system, as documented *** though probably not 
up-to-date *** in the Macintosh Operating System Reference Manual. 
You need to know about this only if you want to understand how 
resources are implemented internally; you don't have to know it to 
be able to use the Resource Manager. 

If you're going to write your own program to create and edit resource 
files, you also need to know the exact format of the data that defines 
each type of resource. The documentation for the Toolbox unit that 
deals with a particular type of resource will tell you what you need to 
know for that resource. 

The manual begins with an introduction to the Resource Manager and then 
an overview of resource files that contains general information for all 
readers. The next three sections deal with resource identification, 
resource references, and resources within resources; you can skip these 
if you're only going to access the resource file indirectly through 
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other Toolbox units. 

routines and tells how they fit Into the tlo J Manager 

e£feCtS> 

side effects, and so on. 

. • oaoM'nn that gives the exact format 

Following these descriptions is a sect ion pcogram , ers „ ho 

“ f iU srsr^=r!l.s;.r routines from assembly language. 

Finally, there's a summary ^/“"“"“^uffomat for'quick 
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its resources. 

The Resource Manager is initialized by the ^^of the initialization, 
and the system resource file ^^Hpen^when the application starts 
Your application s resource tain P reS ource, the Resource Manager 

up. When instructed to go . ^ resource file and then, 

will normally look first in tho application s^resourc^^ ^ 

“k^i^y to 3 share 8 resour ces "d^r^ “if you 
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Resource Manager will read tne 
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( eye) 

The Resource Manager knows nothing about the formats of 

the data that defines the individual types of resources. 

Only the routines in other Toolbox units that call the 

Resource Manager have this knowledge. 

You can change the ID number, name, or other attributes of a resource. 
For example, you can designate whether the resource should be kept in 
memory or whether, as is normal for large resources, it can be removed 
from memory and read in again when needed. You can also change the 
data defining an existing resource, remove a resource from the resource 
file altogether, or add a new resource to the file. 

Not only can an application's resource file contain resources 
themselves, but it may also contain references to resources defined in 
the system resource file. These references need not be there in order 
for the system resources to be found, because the system resource file 
will be searched anyway; however, they do serve other purposes. One is 
that the reference can have a different name than the system resource 
itself, thus providing an "alias" for the resource. But more 
important, these references let the Finder know what resources the 
application needs, so it can be sure those resources accompany the 
application when it's copied. References to system resources can be 
added or removed with Resource Manager routines. 

Resource files are not limited to applications; anything stored in a 
file can have its own resources. For example, documents will usually 
have resource files containing references to the system resources they 
use, such as fonts and icons. As in an application's resource file, 
these references tell the Finder what resources should go with the 
document when it's copied. An unusual font used in only one document 
can be included in the resource file for that document. 

Although the system resource file is usually where shared resources are 
stored, you can have other resource files that contain resources shared 
by two or more applications (or documents, or whatever). In this case, 
however, the Finder will know nothing about the connection between the 
shared resources and the files that use them, so it's up to you to be 
sure the necessary resources accompany the files when they're copied. 

A number of resource files may be open at one time; the Resource 
Manager searches the files in the reverse of the order that they were 
opened. Since the system resource file is opened when the Resource 
Manager is initialized, it's always searched last. Usually the search 
starts with the most recently opened resource file, but you can change 
it to start with a file that was opened earlier. 
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OVERVIEW OF RESOURCE FILES 


When is a file not a file? 

When it's a resource file. 

A resource file is not a file in the strictest sense. Although it s 
functionally like a file in many ways, it s actually just one of two 
parts, or ‘’forks" , of a file. Every file has a resource fork and a 
data fork. The resource fork of an application file contains not only 
resources used by the application, like menus and fonts, but also the 
application code itself! (See Figure 1.) The code is divided into 
different segments, each of which is a resource; this allows various 
parts of the program to be loaded and purged dynamically . The data 
fork of an application file initially contains nothing, but the 
application may store data there if it likes. 



Figure 1. An Application File 

As shown in Figure 2, the system resource file also has this structure. 
The resource fork contains the system resources and the data fork 
contains the RAM-based Operating System routines. Figure 2 also shows 
the structure of a file containing a document; the resource fork 
contains the document's resources and the data fork contains the data 
that makes up the document. 
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System Resource File Document File 


Figure 2. Other Files 

When the Resource Manager opens a resource file, it returns a number 
greater than (2f , called a reference number , by which you can refer to 
the file when calling other Resource Manager routines. Most of the 
routines, however, don't have such a parameter; instead, they assume 
that the current resource file is where they should perform their 
operation (or begin it, in the case of a search for a resource). The 
current resource file is the last one that was opened, unless you 
specify otherwise with a Resource Manager routine. 

A resource file consists primarily of resource data and a resource map. 
The resource data is the data that actually defines the resources. The 
resource map provides the connection between the identification of a 
resource and its resource data; it leads to the data for resources that 
are defined in the resource file itself, or it contains references to 
resources that are defined in the system resource file. The resource 
map is read into memory when the file is opened, and the resource data 
is read into memory when needed. 

( hand) 

Notice that although we say the Resource Manager searches 
resource files, it actually searches the resource maps 
that were read into memory, and not the resource files 
themselves . 

Once read in, the data for a particular resource may or may not be kept 
in memory, depending on an attribute of the resource that's specified 
in the resource map. Resources defined by a relatively large amount of 
data are usually designated as purgeable , meaning they may be removed 
from the heap ("purged*’) when space is required during memory 
management. Purged resources are later read in again when necessary. 

To modify resources, you change the resource data or resource map in 
memory. The changes become permanent only when the application 
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terminates or when you call a routine specifically for updating or 
closing the resource file. 

Resource files also contain some file information that's accessed by 
the Finder: the icon to be displayed for the file; a user-modifiable 
text comment; and a copy of part of the directory entry for the file. 


RESOURCE IDENTIFICATION 

In a resource file, every resource is assigned a type and an ID number, 
and may or not be given a name. When calling a Resource Manager 
routine to access a resource, you refer to the resource by specifying 
its type and either its ID number or its name. This section gives some 
general information about resource identification; details about the 
Resource Manager routine calls and the format of a resource file are 
provided later. 

The resource type is a sequence of four characters. Its Pascal data 
type is: 

TYPE ResType = PACKED ARRAY [1..4] OF CHAR; 

The standard resource types recognized by the Macintosh User Interface 
Toolbox are as follows: 


Resource type 

Meaning 

'WIND' 

Window template 

'WDEF' 

Window definition function 

'MENU' 

Menu 

'MDEF' 

Menu definition procedure 

'MBAR' 

Menu bar 

' CNTL' 

Control template 

' CDEF' 

Control definition function 

'DLOG' 

Dialog template 

' ALRT' 

Alert template 

'DITL' 

Item list in a dialog or alert 

'FONT' 

Font 

' FWID' 

Font widths 

'ICON' 

Icon 

'CURS' 

Cursor 

'PICT' 

Picture 

'PAT ' 

Pattern 

'PAT#' 

Pattern list 

'STR ' 

String 

' DRVR' 

Desk accessory or other I/O driver 

'KEYC' 

Keyboard configuration 

'CODE' 

Application code segment 




( eye) 

Uppercase and lowercase letters ARE distinguished in 
resource types. For example, "Menu’* will not be 
recognized as the resource type for menus. 
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Notice that some of the resources listed in the above table are 
" templates” . A template of something contains information from which 
the thing can be created; it is not the thing itself. For example, a 
window template contains information from which the Window Manager can 
create a window. The Window Manager creates its own window data 
structure and never needs to access the template again. 

Any four-character sequence is valid as a resource type. You can use 
any such sequence (except those listed above) for resource types 
specific to your application, but you should choose names that are 
meaningful. 

Within each type, every resource is assigned a different ID number, or 
resource ID . Resources of different types may have the same resource 
ID. The standard resources in the system resource file are usually 
numbered starting from 0. If you want the ID numbers of your own 
resources not to conflict with those of the system resources, you 
should start numbering them from at least 256. * 

A given resource may or may not have a resource name . Like the 
resource ID, the resource name must be unique within each type, but 
resources of different types may have the same name. The Resource 
Manager does not distinguish between uppercase and lowercase in 
resource names. 


RESOURCE REFERENCES 


The connection between the identification of a resource and its 
resource data is provided by the resource map, and the heart of the 
resource map is its resource references . As illustrated in Figure 3, 
there are two kinds of resource reference: 

- Local references, which are references to resources defined in the 
resource file itself. These either point to the resource data in 
the file or, once you have accessed the resource, contain a handle 
to the data in memory. 

- Global references, which are references to resources defined in 
the system resource file. These provide the identification of the 
resource in the system resource file, which in turn leads to a 
local reference to the resource in that file. 
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identification 
of resource 


local 

reference 

global 

reference 


resource map 


resource 

data 

identification 
of resource 
in system 
resource file 


Application’s resource file 
System resource file 

identification 
of resource 
in system 
resource file 



resource 

data 


resource map 


Figure 3. Resource References in Resource Maps 

Every resource reference has its own type, ID number, and optional 
name. In the case of local references, these identify the resource 
itself; a resource's name, for example, is actually the name of a local 
reference to the resource. A global reference may have its own ID 
n,umber and name, different from those of the resource it refers to in 
the system resource file. 

Suppose you're accessing a resource for the first time. You pass the 
identification of the resource to the Resource Manager, which looks for 
a match among all the references in the resource map; if none is found, 
it looks at the references in the resource map of the next resource 
file to be searched. (Remember, it looks in the resource map in 
memory, not in the file.) Eventually it gets to a local reference to 
the resource, which tells it where the resource data is in the file. 
After reading the resource data into memory, the Resource Manager 
stores a handle to the data in the local reference (again, in memory, 
not in the file) and returns the handle so you can use it to refer to 
the resource in subsequent routine calls. 

( hand) 

For brevity, a handle to the resource data for a resource 
is referred to as simply a handle to the resource. 

Every resource reference also has certain resource attributes which 
determine how the resource should be dealt with. There are eight such 
attributes. In the routine calls for setting or reading them, each 
attribute is specified by a bit in the low-order byte of a word, as 
illustrated in Figure 4. 
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-» 1 if global reference, 0 if local reference 
1 if read into system heap, 0 if application heap 
1 if purgeable, 0 if not 
* 1 if locked, 0 if not 

> 1 if protected, 0 if not 

> 1 if to be " preloaded “, 0 if not 

» 1 if to be written to resource file, 0 if not 

1 if newly added resource, 0 if not 


low-order byte 

(high-order byte is ignored) 

Figure 4. Resource Attributes 

The Resource Manager provides a predefined constant for each attribute, 
in which the bit corresponding to that attribute is set. 

CONST resGlobal = 128; 
resSysHeap = 64; 
resPurgeable = 32; 
resLocked = 16; 
resProtected = 8; 
resPreload « 4; 
resChanged = 2; 
resAdded - 1; 

( hand) 

Although passed and returned in a low— order byte, the 
attributes are stored in a high-order byte in the 
resource file, as described later under ’’Format of a 
Resource File”. 

The resGlobal, resSysHeap, and resPurgeable attributes are 
self-explanatory; the others are explained in the following paragraphs. 

A locked resource is neither relocatable nor purgeable. So when the 
resLocked attribute is set, it overrides the resPurgeable attribute. 

If the resProtected attribute is set, the application cannot use 
Resource Manager routines to do any of the following to the resource: 
set the ID number, type, or name in the resource reference; remove the 
resource from the resource file; or remove the global reference to it, 
if it^s a system resource. The routine that sets the resource 
attributes may be called, however, to remove the protection or just 
change some of the other attributes. 
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The resPreload attribute tells the Resource Manager to read the 
resource data for this resource into memory immediately after opening 
the resource file. This is useful for reading in alert templates, for 
example, so that the disk won't be accessed just for an alert that 
beeps . 

The resChanged and resAdded attributes are used only while the resource 
map is in memory, and should be 0 in the resource file. The resChanged 
attribute tells the Resource Manager whether this resource has been 
changed. The resAdded attribute is set for newly added resources. 

( eye) . 

Your application should not change the settings of the 
resGlobal and resAdded attributes. 


RESOURCES WITHIN RESOURCES 


A resource in a resource file may point to another resource in the 
file. Usually this is done with the ID number of the other resource. 
For example, the resource data defining a menu points to the menus s 
definition procedure (a separate resource) by including the ID number 
of the item list. To work with the resource data in memory, however, 
you instead want to have a handle to the other resource. Since a 
handle occupies two words, the ID number in the resource file is 
followed by a word containing 0; these two words together serve as a 
placeholder for the handle. Once the other resource has been read into 
memory, these two words can be replaced with a handle to it. See 
Figure 5 for an illustration of a menu pointing to a menu definition 
procedure. 






Placeholder J 
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for handle 
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i ' 1 
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Application's 
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resource file 


procedure 



Menu definition 
procedure 


Figure 5. How Resources Point to Resources 
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In the case of menus, the Menu Manager routine GetMenu calls the 
Resource Manager to read the menu and the menu definition procedure 
into memory, and then replaces the placeholder in the menu with the 
handle to the procedure. There may be other cases where you will call 
the Resource Manager directly and will store the handle yourself. 

( hand) 

The ID number alone does not suffice to identify the 
other resource. When calling the routine to get the 
handle to that resource, the application must pass both 
the ID number and the type of the resource. 


USING THE RESOURCE MANAGER 


This section discusses how the Resource Manager routines fit into the 
general flow of an application program and gives you an idea of which 
routines you'll need to use. The routines themselves are described in 
detail in the next section. 

Resource Manager initialization happens automatically when the system 
starts up: the system resource file is opened and its resource map is 
read into memory. Your application's resource file is opened when the 
application starts up; you can call CurResFile to get its reference 
number. You can also call OpenResFile to open any resource file that 
you specify by name, and CloseResFile to close any resource file. A 
function named ResError lets you check for errors during file opening 
and closing or any file I/O operation performed by the Resource 
Manager. 

( hand) 

To use the Resource Manager indirectly through other 
Toolbox units, these are the only routines you need to 
know about; you can skip to their descriptions in the 
next section. 

Normally when you want to access a resource, you'll identify it by type 
and ID number (or type and name) in a call to GetResource (or 
GetNamedResource) . In special situations, such as when you want to 
look at all the resources in a resource file, you may want the Resource 
Manager to tell you all the resource types in the file and to access 
every resource of each type. There are two functions which, used 
together, will tell you all the resource types accessible through the 
current resource file: CountTypes and GetlndType. Similarly, 
CountResources and GetlndResource may be used to access all resources 
of a particular type. 

If you don't specify otherwise, any routine that accesses a resource 
reads the resource data into memory and returns a handle to it. This 
is usually what you'll want. Sometimes, however, you may not need the 
data to be in memory. You can use a procedure named SetResLoad to tell 
the Resource Manager not to read the resource data into memory when a 
resource is accessed; in this case, you'll just get an empty handle for 
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the resource (a pointer to a NIL master pointer). You can pass the 
empty handle to routines that operate only on the resource map (such as 
the routine that sets resource attributes), but of course you can't 
access the resource data through it. Should you later want to read the 
resource data into memory, you can do so with the LoadResource 
procedure. 

Once you have a handle to a resource, you can call GetResInfo or 
GetResAttrs to get the information stored for that resource in the 
resource map, or you can access the resource data through the handle 
(if the resource data is in memory). If the resource points to another 
resource, you can call BeginSubResource and EndSubResource to 
temporarily change which resource file is searched first, to ensure 
that the resource pointed to will be taken from the right resource 
file. 

Usually you'll just be reading resources from previously created 
resource files with the routines described above. You may, however, 
want to modify existing resources or even create your own resource 
file. To create your own resource file, you need to call CreateResFile 
(followed by OpenResFile to open it). There are a number of routines 
that will add to or modify the resource map of the current resource 
file. You can call AddResource with a handle to data that you want to 
be entered as resource data in the current resource file, and you can 
call any of a number of procedures to modify resources already in the 
resource map. 

- To remove a resource, call RmveResource. 

— To add or remove a reference to a system resource, call 
AddReference or RmveRef erence. 

— If you've changed the resource data for a resource and want the 
changed data to be written to the resource file, call 
ChangedR.esource . 

- To change the information stored for a resource in the resource 
map, call SetResInfo or SetResAttrs. If you want the change to be 
written to the resource file, call ChangedResource. (Remember 
that ChangedResource will also cause the resource data itself to 
be written out.) 

All these procedures change only the resource map in memory; the 
changes are written to the resource file when the application 
terminates (at which time all resource files other than the system 
resource file are updated and closed) or when one of the following 
routines is called: 

- CloseResFile , which updates the resource file before closing it. 

— UpdateResFile , which simply updates the resource file. 

- WriteResource , which you call to write the resource data for a 
specified resource to the resource file. 
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This section describes all the Resource Manager procedures and 
functions. They are presented in their Pascal form; for information on 
using them from assembly language, see "Using the Toolbox from Assembly 
Language" *** for now, see the QuickDraw manual *** and also "Notes For 
Assembly-Language Programmers" in this manual. 


Initializing the Resource Manager 


FUNCTION InitResources : INTEGER; 

InitResources is called by the system when it starts up, and should not 
be called by the application. It initializes the Resource Manager, 
opens the system resource file, reads the resource map from the file 
into memory, and returns a reference number for the file. 

( hand) 

The application doesn't need the reference number for the 
system resource file, because every Resource Manager 
routine that has a reference number as its parameter 
interprets 0 to mean the system resource file. 


PROCEDURE RsrcZonelnit ; 

RsrcZonelnit is called automatically when your application starts up, 
to initialize the resource map read from the system resource file; 
normally you'll have no need to call it directly. First RsrcZonelnit 
closes all open resource files except the system resource file. Then, 
for every system resource whose resSysHeap attribute is 0 (meaning the 
resource is read into the application heap) , it removes the handle to 
the resource from the resource map. This lets the Resource Manager 
know that the resource will have to be read in again (since the 
previous application heap is no longer around) . 


Opening and Closing Resource Files 


PROCEDURE CreateResFile (fileName: Str255); 

CreateResFile creates a resource file containing no resource data or 
file information. If there's no file at all with the given name, it 
also creates an empty data fork for the file. If there's already a 
resource file with the given name (that is, a resource fork that isn't 
empty), an error occurs; the ResError function will return the 
appropriate error code (as described below under "Checking For 
Errors") . 
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( hand) 

Before you can work with the resource 
open it with OpenResFile. 


file, you need to 


\ 

FUNCTION OpenResFile (fileName: Str255) : ^ TEGER ’ - 

OpenResFile opens the resource file having the given name. It reads 
the resource map from the file into memory and returns a reference 
number for the file. If the resource file is already open, it simply 
returns the reference number. 


You don't have to call OpenResFile to open the system 
resource file or the application's resource file, because 
they're opened when the system and the application start 
up, respectively. To get the reference number of the 
application's resource file, you can call CurResFile 
(below) . 


If the file cannot be opened, OpenResFile returns -1; to learn the 
exact nature of the problem, you can get the error code from the 
ResError function (described below under Checking or rrors )• 
example, an error occurs if there's no resource file with the given 

name. 


FUNCTION CurResFile : INTEGER; 


CurResFile returns the reference number of the 
You can call it when the application starts up 
number of its resource file. 


current resource file, 
to get the reference 


PROCEDURE CloseResFile (refNum: INTEGER); 

Given the reference number of a resource file, CloseResFile does the 
following: 

- Updates the resource file by calling the UpdateResFile procedure. 
(For more information, see "Modifying Resources" below.) 

- Deallocates the memory occupied by every resource defined in the 
resource file. 

- Closes the resource file. 


If there's no resource file open with the given reference number 
CloseResFile does nothing. The reference number 0 represents t 
system resource file, but if you ask to close this file, CloseResFile 
will first close all other open resource files. 


A CloseResFile of every open resource file except the system 
file is done automatically when the application terminates. 


resource 
So you 
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only need to call CloseResFile if you want to close the system resource 
file, or if you want to close any resource file before the application 
terminates. 


Checking for Errors 


FUNCTION ResError : INTEGER; 

ResError indicates whether an error occurred the last time a Resource 
Manager routine attempted to perform a file I/O operation or to read a 
resource into memory. If no error occurred, it returns 0; otherwise, 
it returns one of the file I/O error codes or the Memory Manager ’'out 
of memory" error code. (See the Macintosh Operating System Reference 
Manual for the exact codes.) You can call this function to check for 
an error after each of the following: system startup, which calls 
InitResources ; application startup, which opens the application's 
resource file; CreateResFile; OpenResFile; CloseResFile; 

GetlndResource , GetResource, or GetNamedResource, if you haven't called 
SetResLoad( FALSE) ; LoadResource; UpdateResFile; and WriteResource. 


Getting Resource Types 


FUNCTION CountTypes : INTEGER; 

CountTypes returns the number of resource types that are accessible 
through the resource map of the current resource file. 


FUNCTION GetlndType (index: INTEGER) : ResType; 

Given an index ranging from 1 to CountTypes (above), GetlndType returns 
a resource type. Called repeatedly over the entire range for the 
index, it returns all the resource types accessible through the 
resource map of the current resource file. If the given index isn't in 
the range from 1 to CountTypes, GetlndType returns ' ' (four 

spaces) . 


Accessing Resources 


PROCEDURE SetResLoad (load: BOOLEAN); 

Normally, the routines that return handles to resources (described 
below) read the resource data into memory if it's not already in 
memory. SetResLoad( FALSE) affects all those routines so that they will 
not read the resource data into memory. SetResLoad(TRUE) restores the 
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normal state. 

( eye) 

If you call SetResLoad(FALSE) , but sure to restore the 
normal state as soon as possible, because other Toolbox 
units that call the Resource Manager rely on it. 


FUNCTION CountResources (theType: ResType) : INTEGER; 

CountResources returns the number of resources of the given type that 
are defined in all open resource files. 


FUNCTION GetlndResource (theType: ResType; index: INTEGER) : Handle; 

Given an index ranging from 1 to CountResources( theType) , 
GetlndResource returns a handle to a resource of the given type (see 
CountResources, above). Called repeatedly over the entire range for 
the index, it returns handles to all resources of the given type that 
are defined in all open resource files. GetlndResource reads the 
resource data into memory if it's not already in memory, unless you've 
called SetResLoad(FALSE) . 

( eye) 

If you've called SetResLoad(FALSE) , and this is the first 
time you've accessed this resource, or the data has been 
purged since it was last read in, the handle returned 
will be an empty handle. When you want to read the data 
in, you can call LoadResource (see below). 

If the given index isn't in the range from 1 to 

CountResources( theType) , GetlndResource returns NIL. It also returns 
NIL if the resource is to be read into memory but won't fit; in this 
case, the ResError function will return the appropriate error code. 

( hand) 

Notice that CountResources and GetlndResource apply to 
all open resource files, unlike CountTypes and 
GetlndType, which apply only to the current resource 
file. 


FUNCTION GetResource (theType: ResType; thelD: INTEGER) : Handle; 

GetResource returns a handle to the resource having the given type and 
ID number, reading the resource data into memory if it's not already in 
memory and if you haven't called SetResLoad(FALSE) (see the note above 
for GetlndResource) . GetResource looks in the current resource file 
and all resource files opened before it, in the reverse of the order 
that they were opened; the system resource file is searched last. If 
it doesn't find the resource, GetResource returns NIL. It also returns 
NIL if the resource is to be read into memory but won t fit; in this 
case, the ResError function will return the appropriate error code. 
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FUNCTION GetNamedResource (theType: ResType; name: Str255) : Handle; 

GetNamedResource returns a handle to the resource having the given type 
and name, reading the resource data into memory if it s not already in 
memory and if you haven't called SetResLoad(FALSE) (see the note above 
for GetlndResource) • GetNamedResource looks in the current resource 
file and all resource files opened before it, in the reverse of the 
order that they were opened; the system resource file is searched last. 
If it doesn't find the resource, GetNamedResource returns NIL. It also 
returns NIL if the resource is to be read into memory but won t fit; in 
this case, the ResError function will return the appropriate error 
code. 


PROCEDURE LoadResource ( theResource : Handle); 

Given a handle to a resource (returned by GetlndResource, GetResource, 
or GetNamedResource) , LoadResource reads that resource into memory if 
it's not already in memory. If the resource is already in memory, 
LoadResource does nothing. 

( hand) 

SetResLoad has no effect on this procedure. 


PROCEDURE ReleaseResource (theResource: Handle); 

Given a handle to a resource, ReleaseResource deallocates the memory 
occupied by the resource data, if any, and disposes of the handle 
(removing it from the resource map so that it s no longer this 
resource's handle). Use this procedure only after you're completely 
through with a resource. ReleaseResource is most useful for resources 
that are not purgeable, since memory occupied by purgeable resources is 
automatically freed when needed. 


PROCEDURE DetachResource (theResource: Handle); 

Given a handle to a resource, DetachResource removes the handle from 
the resource map so that it's no longer recognized as this resource's 
handle. It's useful only in the unusual case that you don't want a 
resource to be deallocated when a resource file is closed. 


Setting the Current Resource File 

See also CurResFile under "Opening and Closing Resource Files” above. 


PROCEDURE BeginSubResource (theResource: Handle); 

Given a handle to a resource, BeginSubResource sets the current 
resource file to the one in which that resource is defined. This is 
useful if you're working with a resource that points to another 
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resource; you can call BeginSubResource with a handle to the original 
resource before calling GetResource to access the resource it points 
to, to ensure that the latter will be taken from the same resource 
file. 

Every call to BeginSubResource should be balanced by a call to 
EndSubResource (see below). 


PROCEDURE EndSubResource; 

EndSubResource resets the current resource file to what it was before 
BeginSubResource (above) was called. 

( eye) 

BeginSubResource can remember only one previous resource 
file (for later restoration by EndSubResource), so you 
should not nest one BeginSubResource-EndSubResource pair 
within another. 


PROCEDURE UseResFile (refNum: INTEGER); 

Given the reference number of a resource file, UseResFile sets the 
current resource file to that file. If there^s no resource file open 
with the given reference number, UseResFile does nothing. The 
reference number 0 represents the system resource file. 

This procedure is useful for changing which resource file is searched 
first. For example, if you no longer want to override a system 
resource with one by the same name in your applications resource file, 
you can call UseResFile(0) to make the search begin (and end) in the 
system resource file. 


Getting Resource Information 


PROCEDURE GetResInfo ( theResource : Handle; VAR thelD: INTEGER; VAR 
theType: ResType; VAR name: Str255); 

Given a handle to a resource, GetResInfo returns the ID number, type, 
and name of the resource. If the current resource file contains a 
global reference to the resource, it returns the ID number, type, and 
name of the global reference, which may be different from those of the 
resource itself in the system resource file. 


FUNCTION GetResAttrs (theResource: Handle) : INTEGER; 

Given a handle to a resource, GetResAttrs returns the resource 
attributes for the resource in the low-order byte of the integer result 
(as described earlier under "Resource References )• If the current 
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resource file contains a global reference to the resource, GetResAttrs 
returns the resource attributes of the global reference, which may be 
different from those of the resource itself in the system resource 
file. 


Modifying Resources 

Except for UpdateResFile and WriteResource , all the routines described 
below change the resource map in memory and not the resource file 
itself . 


PROCEDURE SetResInfo ( theResource : Handle; thelD: INTEGER; name: 

Str255) ; 

Given a handle to a resource, SetResInfo sets the ID number and name of 
the resource to the given ID number and name. If the current resource 
file contains a global reference to the resource, SetResInfo sets only 
the ID number and name of the global reference. In either case, if you 
pass NIL for the name parameter, the name will not be changed. If the 
resProtected attribute for the resource is set, SetResInfo does 
nothing. 

( eye) 

If the resource is defined in the system resource file 
but the current resource file doesn't contain a global 
reference to it, SetResInfo will set the ID number and 
name in the system resource file itself. This is a 
dangerous practice, because other applications may 
already access the resource and may not work properly if 
its identification is changed. 

The change will be written to the resource file when the file is 
updated if you follow SetResInfo with a call to ChangedResource . 

( eye) 

Even if you don't call ChangedResource for this resource, 
the change may be written to the resource file when the 
file is updated. If you've EVER called ChangedResource 
for ANY resource in the file, or if you've made other 
modifications such as adding or removing resources or 
resource references, the Resource Manager will write out 
the entire resource map when it updates the file, so all 
changes made to resource information in the map will 
become permanent. If you want any changes to be 
temporary in this case, you'll have to restore the 
original information before the file is updated. 


PROCEDURE SetResAttrs (theResource: Handle; attrs: INTEGER); 

Given a handle to a resource, SetResAttrs sets the resource attributes 
for the resource to the low-order byte of the given integer (as 
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described earlier under "Resource References"). If the current 
resource file contains a global reference to the resource, SetResAttrs 
sets only the resource attributes of the global reference. 

( hand) 

To set the resChanged attribute, you must call 
ChangedResource instead (see below). 

The attributes set with SetResAttrs will be written to the resource 
file when the file is updated if you follow SetResAttrs with a call to 
ChangedResource. However, even if you don't call ChangedResource for 
this resource, the change may be written to the resource file when the 
file is updated. See the last warning above for SetResInfo. 


PROCEDURE ChangedResource ( theResource : Handle); 

Call ChangedResource after changing either the information about a 
resource in the resource map (as described above under SetResInfo and 
SetResAttrs) or the resource data for a resource, if you want the 
change to be permanent. Given a handle to a resource, ChangedResource 
sets the resChanged attribute for the resource. This attribute tells 
the Resource Manager to do both of the following: 

- Write the resource data for the resource to the resource file when 
the file is updated or when WriteResource is called, and 

- Write the entire resource map to the resource file when the file 
is updated. 

( eye) 

If you change information in the resource map with 
SetResInfo or SetResAttrs and then call ChangedResource, 
remember that not only the resource map but also the 
resource data will be written out when the resource file 
is updated. 


PROCEDURE AddResource (theData: Handle; theType: ResType; thelD: 

INTEGER; name: Str255); 

Given a handle to data in memory (not a handle to an existing 
resource) , AddResource makes the Resource Manager treat the data as 
resource data, by adding a local reference to it to the current 
resource file. (It sets the resChanged attribute for the resource, so 
the data will be written to the resource file when the file is updated 
or when WriteResource is called.) *** Currently AddResource doesn't 
work for a newly created resource file. (Note that this means 
CreateResFile isn't useful at this time.) *** 
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PROCEDURE RmveResource ( theResource : Handle); 

Given a handle to a resource defined in the current resource file, 
RmveResource removes the local reference to the resource; the resource 
data will be removed from the resource file when the file is updated. 
If the resProtected attribute for the resource is set, or if the given 
handle isn't a handle to a resource defined in the current resource 
file, RmveResource does nothing. 

( eye) 

It's dangerous to remove a resource from the system 
resource file, because all global references to it will 
become invalid. 


PROCEDURE AddReference (theResource: Handle; thelD: INTEGER; name: 

Str255); 

Given a handle to a system resource, AddReference adds a global 
reference to the resource to the current resource file, giving it the 
ID number and name specified by the parameters. (It sets the 
resChanged attribute for the resource, so the reference will be written 
to the resource file when the file is updated.) If the current 
resource file already contains a global reference to the specified 
resource, or if the given handle isn't a handle to a system resource, 
AddReference does nothing. 


PROCEDURE RmveRef erence (theResource: Handle); 

Given a handle to a system resource, RmveRef erence removes the global 
reference to the resource from the current resource file. (The 
reference will be removed from the resource file when the file is 
updated.) In any of the following cases, RmveRef erence does nothing: 
the resProtected attribute for the resource is set; there's no global 
reference to the resource in the current resource file; or the given 
handle isn't a handle to a system resource. 


PROCEDURE UpdateResFile (refNum: INTEGER); 

Given the reference number of a resource file, UpdateResFile does the 
following: 

- Changes, adds, or removes resource data in the file as appropriate 
to match the map. Remember that changed resource data will be 
written out only if you called ChangedResource. 

- Compacts the resource file, closing up any empty space that may 
have been created when the file was updated. (If the size of a 
changed resource is greater than its original size in the resource 
file, it's written at the end of the file rather than at its 
original location, leaving empty space at that location.) 
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- Writes out the resource map of the resource file, if you ever 

called ChangedResource for any resource in the file or if you made 
other modifications such as adding or removing resources or 
resource references. All changes to resource information in the 
map will become permanent as a result of this, so if you want any 
such changes to be temporary, you must restore the original 
information before calling UpdateResFile. 

If there's no open resource file with the given reference number, it 
does nothing. The reference number 0 represents the system resource 
file. 

The CloseResFile procedure calls UpdateResFile before it closes the 
resource file, so you only need to call UpdateResFile yourself if you 
want to update the file without closing it. 

( eye) 

If you changed the resource data for a resource that 
points to another resource, and you're not calling a 
Toolbox routine that will replace the handle to the other 
resource with its placeholder (the ID number followed by 
0) , be sure to replace the handle yourself. 


PROCEDURE WriteResource ( theResource: Handle); 

Given a handle to a resource, WriteResource checks the resChanged 
attribute for that resource and, if it's set (which it will be if you 
called ChangedResource or AddResource) , writes its resource data to the 
resource file and clears its resChanged attribute. See the warning 
above for UpdateResFile. 

Since the resource file is updated when the application terminates or 
when you call UpdateResFile (or CloseResFile, which calls 
UpdateResFile) , you only need to call WriteResource if you want to 
write out just one or a few resources right away. 


PROCEDURE SetResPurge (install: BOOLEAN); 

SetResPurge(TRUE) sets a "hook" in the Memory Manager such that before 
purging a handle, the Memory Manager will first pass the handle to the 
Resource Manager. The Resource Manager will determine whether the 
handle is that of a resource in the application heap and, if so, will 
call WriteResource to write the resource data for that resource to the 
resource file if its resChanged attribute is set (see WriteResource 
above). SetResPurge(FALSE) restores the normal state, clearing the 
hook so that the Memory Manager will once again purge handles without 
checking with the Resource Manager. 

( eye) 

SetResPurge(TRUE) is useful in applications that modify 
purgeable resources, but if your application does this 
you should be sure it's really what you want to do. 
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Notice that you won t know exactly when the resources are 
being written out; most applications will want more 
control than this, or won't want resources being modified 
to be purgeable at all. 


FORMAT OF A RESOURCE FILE 

This section gives the exact format of a resource file, which you need 
to know if you're writing a program that will create or modify resource 
i es directly. You don't have to know the exact format to be able to 
use the Resource Manager routines* 






Resource header 
(16 bytes) 

Copy of directory entry 
(112 bytes) 

File icon 
(128 bytes) 


File comment 
(256 bytes) 


Other data 


> Resource data 


Resource map 


y 512 bytes 


optional 


Figure 6* Format of a Resource File 


As illustrated in Figure 6, every resource file begins with a resource 
header * The resource header gives the offsets to and lengths of the 
resource data and resource map parts of the file, as follows: 


Number of bytes 
4 bytes 

4 bytes 

4 bytes 
4 bytes 


Contents 

Offset from beginning of resource file 
to resource data 

Offset from beginning of resource file 
to resource map 

Length of resource data in bytes 
Length of resource map in bytes 


By convention, file information used by the Finder immediately follows 
the resource header: 


Number of bytes 
112 bytes 
128 bytes 
256 bytes 


Contents 

Partial copy of directory entry for this file 
Icon to be displayed for this file 
Comment for this file 


/«\ 
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The file comment may be followed by other data if desired. (Someone 
using the resource file may want special data to be carried along with 
the file.) 

The resource data follows the file comment (or other data, if any). It 
consists of the following for each resource defined in the file: 


Number of bytes Contents 

For each resource: 

2 bytes Length of following resource data in bytes 

n bytes Resource data for this resource 

To learn exactly what the resource data is for a particular type of 
resource, see the documentation on the Toolbox unit that deals with 
that resource. 

After the resource data, the resource map begins as follows: 


Number of bytes Contents 

16 bytes 0 (reserved for copy of resource header) 

4 bytes 0 (reserved for handle to next resource map 

to be searched) 

2 bytes 0 (reserved for file reference number) 

2 bytes Map attributes, used internally by the 

Resource Manager 

2 bytes Offset from beginning of resource map 

to type list (see below) 

2 bytes Offset from beginning of resource map 

to resource name list (see below) 

The resource map continues with the type list, which contains the 
following: 


Number of bytes 
2 bytes 

For each type: 
4 bytes 
2 bytes 

2 bytes 


Contents 

Number of resource types in the map (minus 1) 
Resource type 

Number of resources of this type in the map 
(minus 1) 

Offset from beginning of type list 
to reference list for resources of this type 


This is followed by the reference list for each type of resource, which 
contains the resource references for all resources of that type. The 
reference lists are contiguous and in the same order as the types in 
the type list. The format of a reference list is as follows: 
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Number of bytes 
For each reference 
of this type: 

2 bytes 
2 bytes 
4 bytes 


4 bytes 


Contents 


Resource ID 

Resource name ID (see below) 

If local reference, offset from beginning 
of resource data to length of data for this 
resource, with resource attributes in 
high-order byte 

If global reference, resource attributes in 
high-order byte, 0 in remaining bytes (which 
are ignored) 

If local reference, 0 (reserved for handle 
to resource) 

If global reference, identification of 
resource in system resource file: resource 
ID in high-order word and resource name ID 
in low-order word 


The resource name ID is used only internally by the Resource Manager, 
to associate a particular resource ID and type with a resource name 
string. The connection between a resource name ID and the 
corresponding string is made in the resource name list of the resource 
map, which follows the reference list and has this format: 


Number of bytes 
2 bytes 

For each name ID: 
2 bytes 
2 bytes 

For each name: 

1 byte 
n bytes 


Contents 

Number of resource names in the map (minus 1) 
Resource name ID 

Offset from beginning of resource name list 
to resource name associated with this name ID 

Length of following resource name in bytes 
Characters of resource name 


NOTES FOR ASSEMBLY-LANGUAGE PROGRAMMERS 


Information about how to use the User Interface Toolbox from assembly 
language is given elsewhere. *** For now, see the QuickDraw manual. 
*** This section contains special notes of interest to programmers who 
will be using the Resource Manager from assembly language. 

All Resource Manager routines save all registers except A0 and D0. 

The primary aid to assembly-language programmers is a file named 
ToolEqu.Text . If you use .INCLUDE to include this file when you 
assemble your program, the following globals will be available: 
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Global 

curMap 

resLoad 

resErr 


Contents 

Reference number of current resource file 
Value of SetResLoad state 
Value of ResError 


Furthermore, the file ResEqu.Text contains constants for the various 
resource types and for the ID numbers of standard resources. 
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SUMMARY OF THE RESOURCE MANAGER 


CONST resGlobal 

resSysHeap = 
resPurgeable = 
resLocked = 
resProtected = 
resPreload = 
resChanged = 
resAdded = 


128; 

64; 

32; 

16; 

8 ; 

4; 

2 ; 

1 ; 


TYPE ResType = PACKED ARRAY [1..4] OF CHAR; 


Initializing the Resource Manager 

FUNCTION InitResources : INTEGER; 
PROCEDURE RsrcZonelnit; 


Opening and Closing Resource Files 


PROCEDURE CreateResFile (filename: Str255); 

FUNCTION OpenResFile (fileName: Str255) : INTEGER; 
FUNCTION CurResFile : INTEGER; 

PROCEDURE CloseResFile (refNum: INTEGER); 


Checking for Errors 


FUNCTION ResError : INTEGER; 


Getting Resource Types 

FUNCTION CountTypes : INTEGER; 

FUNCTION GetlndType (index: INTEGER) : ResType; 


Accessing Resources 

PROCEDURE SetResLoad (load: BOOLEAN); 

FUNCTION CountResources (theType: ResType) : INTEGER; 

FUNCTION GetlndResource (theType: ResType; index: INTEGER) : Handle; 

FUNCTION GetResource (theType: ResType; thelD: INTEGER) : Handle; 

FUNCTION GetNamedResource (theType: ResType; name: Str255) : Handle; 
PROCEDURE LoadResource (theResource : Handle); 

PROCEDURE ReleaseResource (theResource: Handle); 

PROCEDURE DetachResource (theResource: Handle); 
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Setting the Current Resource File 

PROCEDURE BeginSubResource ( theResource: Handle); 
PROCEDURE EndSubResource; 

PROCEDURE UseResFile (refNum: INTEGER); 


Getting Resource Information — 

PROCEDURE GetResInfo (theResource: Handle; VAR thelD: INTEGER; VAR 

theType: ResType; VAR name: Str255;; 

FUNCTION GetResAttrs (theResource: Handle) : INTEGER; 


Modifying Resources 


PROCEDURE SetResInfo 

PROCEDURE SetResAttrs 
PROCEDURE ChangedResource 
PROCEDURE AddResource 

PROCEDURE RmveResource 
PROCEDURE AddReference 

PROCEDURE RmveReference 
PROCEDURE UpdateResFile 
PROCEDURE WriteResource 
PROCEDURE SetResPurge 


(theResource: Handle; thelD: INTEGER; name: 
Str255) ; 

(theResource: Handle; attrs: INTEGER); 
(theResource: Handle); 

(theData: Handle; theType: ResType; thelD: 
INTEGER; name: Str255) ; 

(theResource: Handle); 

(theResource: Handle; thelD: INTEGER; name. 
Str255) ; 

(theResource: Handle); 

(refNum: INTEGER); 

(theResource: Handle); 

(install: BOOLEAN); 
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SUMMARY OF THE RESOURCE FILE FORMAT 


Resource 

Header 


4 bytes 
4 bytes 
4 bytes 
4 bytes 


Offset to resource data 
Offset to resource map 
Length of resource data 
Length of resource map 


File 112 bytes 

Information 128 bytes 

256 bytes 


Partial copy of directory entry for file 
File icon 
File comment 


Resource 

Data 


For each resource: 

2 bytes Length of following resource data 

n bytes Resource data for this resource 


Resource 

Map 


Type list 


Reference 
list (one 
per type, 
contiguous, 
same order 
as in type 
list) 


Resource 
name list 


16 bytes 
4 bytes 

2 bytes 
2 bytes 
2 bytes 
2 bytes 
2 bytes 

For each type: 

4 bytes 
2 bytes 
2 bytes 

For each reference 
of this type: 

2 bytes 
2 bytes 
4 bytes 


4 bytes 


2 bytes 

For each name ID: 
2 bytes 
2 bytes 


For each name: 
1 byte 
n bytes 


Reserved for copy of resource header 
Reserved for handle to next resource map 
to be searched 

Reserved for file reference number 

Map attributes 

Offset to type list 

Offset to resource name list 

Number of resource types (minus 1) 

Resource type 

Number of resources of this type (minus 1) 
Offset to reference list for this type 


Resource ID 
Resource name ID 

If local, offset to length of resource 
data, with resource attributes in 
high-order byte 

If global, resource attributes in 
high-order byte, (0 in remaining bytes 
If local, reserved for handle to resource 
If global, identification of resource in 
system resource file: resource ID in 
high-order word and resource name ID in 
low-order word 

Number of resource names (minus 1) 
Resource name ID 

Offset to resource name associated with 
this name ID 

Length of following resource name 
Characters of resource name 
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current resource file: The last resource file opened, unless you 
specify otherwise with a Resource Manager routine* 

empty handle: A pointer to a NIL master pointer. 

global reference: In an application's resource file, a resource 
reference to a system resource. It provides the identification of the 
resource in the system resource file. 

local reference: A resource reference to a resource defined in the 
same file as the reference; a pointer to the resource data in the file 
or a handle to it in memory. 

purgeable: Able to be removed from the heap ("purged") when space is 

required during memory management. 

reference number: A number by which you can refer to an open resource 
file in Resource Manager routine calls. It's returned when the file is 
opened. 

resource: Data stored in a resource file and managed by the Resource 

Manager, such as a menu, font, or icon. 

resource attribute: One of eight characteristics, specified by bits in 
a resource reference, which determine how the resource should be dealt 
with. 

resource data: The data that defines a resource in a resource file. 

resource file: The resource fork of a file, which contains data 
managed by the Resource Manager, such as menus, fonts, and icons. 

resource header: At the beginning of a resource file, data that gives 
the offsets to and lengths of the resource data and resource map. 

resource ID: A number which, together with the resource type, uniquely 
identifies a resource in a resource file. Every resource has an ID 
number . 

resource map: In a resource file, data which is read into memory when 
the file is opened and which, given a resource type and either a 
resource ID or a resource name, leads to the corresponding resource 
data. 

resource name: A string which, together with the resource type, 
identifies a resource in a resource file. A given resource may or may 
not have a name. 

resource reference: In a resource map, a local reference leading to 
resource data in the same file as the reference, or a global reference 
leading to data in the system resource file. 
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resource type: The type of a resource in a resource file, designated 
by a sequence of four characters (such as "MENU" for a menu). 

system resource: A resource defined in the system resource file. 

system resource file: A resource file defining standard resources, 
accessed if a requested resource wasn^t defined in any of the other 
resource files that were searched. 




ft f 
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ABOUT THIS MANUAL 


This manual introduces you to the "inside” of Macintosh: the Operating 
System, the User Interface Toolbox, and other routines that enable you 
to write an application program. It will help you identify which 
software you need to learn more about and how to proceed with the rest 
of the documentation. *** Eventually it will be an introductory 
chapter in a large manual that describes everything in detail. *** 

( hand) 

This early draft of the manual stresses the User 
Interface Toolbox; later drafts will provide more 
information about the Operating System and other 
software. 

You should already be familiar with the Macintosh User Interface 
Guidelines. A document is available that describes these guidelines, 
which all Macintosh programmers should follow to ensure that the end 
user will be presented with a consistent interface. It would also be 
helpful to have some familiarity with an existing Macintosh application 
program. 

The manual begins with a general overview of the software you"* 11 use to 
write a Macintosh application, followed by individual overviews of the 
User Interface Toolbox and the Operating System. Some general 
information is then given for programmers who will be using the 
software from assembly language rather than Pascal. The next section 
tells you how to proceed with reading the rest of the documentation. 
Finally, there's a glossary of terms used in this manual. 


GENERAL OVERVIEW 


Most of the software you'll use to write a Macintosh application is in 
either the Operating System or the User Interface Toolbox. As 
illustrated in Figure 1, the Operating System is at the lowest level; 
it communicates directly with the hardware and does the basic 
housekeeping" tasks such as interrupt handling, memory management, and 
file I/O. The User Interface Toolbox is a level above the Operating 
System; it's a set of routines and data types (divided into “units”) 
that help you implement the standard Macintosh user interface in your 
application. The Toolbox calls the Operating System when it needs to 
do low-level operations, and at times you'll need to call the Operating 
System directly yourself. 
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A MACINTOSH APPLICATION PROGRAM 


THE USER INTERFACE TOOLBOX 

The Resource Manager 

QuickDraw 

The Font Manager 

The Toolbox Event Manager 

The Window Manager 

The Control Manager 

The Menu Manager 

The Dialog Manager 

TextEdit 

CoreEdit (not in ROM) 

The Desk Manager 
The Toolbox Utilities 
The System Error Handler 
Packages 


THE OPERATING SYSTEM 

The Memory Manager 
The File System 
The Operating System’s 
Event Manager 
The Drivers 
The Segment Loader 
... and more 


THE MACINTOSH HARDWARE 


OTHER LOW-LEVEL SOFTWARE 
Floating-Point Math (not in ROM) 


OTHER HIGH-LEVEL SOFTWARE 
Printing (not in ROM) 








Figure 1. Overview 

Other software is available for performing specialized operations that 
aren't integral to the user interface but may be useful to some 
applications. This includes routines for doing hardcopy printing and 
floating-point math. Such software isn't located in the Macintosh s 
ROM, nor are certain special-purpose Toolbox units (such as CoreEdit, 
for doing text display and editing that are more sophisticated than 
allowed by the basic editing package, TextEdit). The entire Operating 
System and all the generally useful parts of the Toolbox are in the 
ROM. 
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Macintosh applications can be written most easily in Pascal, but for 
more efficient code, you may want to use assembly language or a 
combination of Pascal and assembly language* *** Currently you must 
develop your application on a Lisa computer and convert it to a 
Macintosh-formatted diskette before trying it out. Eventually 
development tools will be available on the Macintosh itself. *** 

With very few exceptions, all routines can be called from either Pascal 
or assembly language. *** Currently the Pascal interface has not been 
set up for a lot of the Operating System routines, but eventually it 
will be. *** 


ABOUT THE USER INTERFACE TOOLBOX 


The Macintosh User Interface Toolbox provides a high-level, easy-to-use 
method for constructing application programs that conform to the 
Macintosh User Interface Guidelines. By offering a common set of 
routines that every application calls to implement the user interface, 
the Toolbox not only ensures consistency but also helps reduce the 
applications code size and development time. 

Flexibility was a major consideration in the design of the Toolbox, 
which is structured to allow the application to remain in control. The 
application receives events (such as mouse and keyboard actions) and 
drives the Toolbox accordingly. It can always use its own code to 
process an event instead of a Toolbox call whenever appropriate. 
Windows, menus, and controls are implemented via procedures to which 
the Toolbox sends messages. Programmers can use the built-in standard 
procedures or ‘'customize** by writing their own procedures to interpret 
the Toolbox messages. 

Also basic to the design of the Toolbox is the implementation of 
resources . Through the resource mechanism, data such as menus and 
icons can be stored separately from the application code for ease of 
modification. For example, a menu stored as a resource can be 
translated to a foreign language without requiring recompilation of the 
application code. 
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Desk Manager 


Dialog Manager 


TextEdit 

CoreEdit 

Control Manager 

Menu Manager 


Window Manager 


Toolbox Utilities 




QuickDraw 

1 1 Toolbox Event Manager 


(To be added; 

System Error Handler 
and Packages) 


Font Manager 
Resource Manager 


Figure 2. Toolbox Units 

Figure 2 shows the Toolbox units in rough order of their level, from 
the lowest level at the bottom to the highest level at the top. At the 
lowest level is the Resource Manager , the unit that reads and writes 
resources. Many of the routines in other units eventually lead to a 
Resource Manager call. Most applications will never call the Resource 
Manager directly. 

All the graphics operations performed by an application are done 
through calls to the QuickDraw unit. Every Toolbox routine that 
affects the screen calls QuickDraw, and you'll often have occasion to 
call it yourself directly. When asked to draw text, QuickDraw calls 
the Font Manager , which supports the use of various character fonts 
(and in turn calls the Resource Manager to read them into memory). 

An application receives events from the Toolbox Event Manager (which 
calls another, lower-level Event Manager in the Operating System). 
Events report the user's actions, such as clicking the mouse button or 
pressing a key, and also serve as a means of communication within the 
Toolbox itself. 

Generally useful operations such as fixed-point arithmetic, string 
manipulation, and logical operations on bits may be performed with the 
Toolbox Utilities . 

All information presented by a standard Macintosh application appears 
in windows on the display screen. The Window Manager provides routines 
for creating and manipulating windows. It keeps track of overlapping 
windows, so you can move windows, change their front-to-back ordering, 
or change their size without concern for how the various windows 
overlap. 

As you would expect, the Control Manager is the part of the User 
Interface Toolbox that deals with controls (such as buttons and check 
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boxes), and the Menu Manager is the part that deals with menus. They 
make it easy for your program to create and manipulate controls and 
menus in a way that's consistent with the Macintosh User Interface 
Guidelines. 

TextEdit and CoreEdit are text editing packages. TextEdit supports 
only the basic text entry and editing capabilities and is especially 
easy to use. CoreEdit is a more sophisticated package; you'll use 
CoreEdit instead of TextEdit if your application is to display text in 
different character styles, fonts, and sizes, or if formatting 
operations such as tabbing are desired. CoreEdit is not in the 
Macintosh ROM and occupies over 6K of memory, whereas TextEdit is in 
the ROM. 

Finally, the Dialog Manager provides routines for implementing dialog 
boxes and the alert mechanism, and the Desk Manager supports the use of 
desk accessories from an application. 

*** To be added: System Error Handler and Packages *** 


ABOUT THE OPERATING SYSTEM 


*** To be written: An overview similar to the above. For now, see 
Chapter 1, "Overview of the Operating System", in the Macintosh 
Operating System Reference Manual. *** 


ABOUT USING ASSEMBLY LANGUAGE 


The assembly-language programmer sometimes has to take special steps to 
access a routine. In particular, special action must be taken to call 
any routine that's stack— based (meaning it receives parameters and 
returns values on the stack). Almost all routines in the Toolbox and 
in the optional specialized software are stack-based. This makes them 
easily callable from Pascal, since the Pascal routine-calling mechanism 
is also stack-based, but to call them from assembly language you must 
first set up the stack properly. After setting up the stack, you 
invoke a macro that traps Into the ROM; the macro has a convenient 
symbolic name, usually an underscore followed by the name of the 
routine. 

The Operating System routines are register-based, so using them from 
assembly language is straightforward. An interface is provided that 
makes many *** (eventually all or nearly all) *** of them accessible 
from Pascal. For the convenience of the Pascal programmer and ease of 
presentation, the routines are shown in their Pascal form; 
assembly-language programmers will be told how to interpret that 
presentation in terms of registers. *** This reflects our current 
intent, not the actual state of the existing Operating System 
documentation. *** 
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WHERE TO GO FROM HERE ; 

*** This section will be considerably rewritten for the final 
comprehensive manual. *** 

The Toolbox documentation will eventually be ordered in such a way that 
you can follow it if you read it sequentially. The proposed order for 
the documentation that's already written is given below. Before you 
begin, you should be familiar with Lisa Pascal and know a little bit 
about the Macintosh's memory management — heaps, handles, and the like. 
For now, you can read about memory management in the introduction to 
Chapter 3.3, "Memory Management Core Routines", in the Macintosh 
Operating System Reference Manual. Information about handles is also 
given in the QuickDraw manual's discussion of regions and the Control 
Manager manual's discussion of control handles. 

The Resource Manager: A Programmer's Guide 

QuickDraw: A Programmer's Guide 

The Font Manager: A Programmer's Guide 

The Event Manager: A Programmer's Guide 

The Window Manager: A Programmer's Guide 

Macintosh Control Manager Programmer's Guide 

The Menu Manager: A Programmer's Guide 

The Dialog Manager: A Programmer's Guide 

TextEdit: A Programmer's Guide *** forthcoming *** 

CoreEdit: A Programmer's Guide 
The Desk Manager: A Programmer's Guide 
The Toolbox Utilities: A Programmer's Guide 
Macintosh Operating System Reference Manual 
The Segment Loader: A Programmer's Guide 
Putting Together a Macintosh Application 

The individual manuals on Toolbox units let you know what information 
is special purpose and can possibly be skipped. Most likely you won't 
need to read everything in each manual and can even skip entire manuals 
altogether. You should at least read the manuals on the Toolbox units 
that deal with the fundamental aspects of the user interface: The 
Resource Manager, QuickDraw, the Toolbox Event Manager, the Window 
Manager, and the Menu Manager. Read the other manuals if you're 
interested in what they discuss, which you should be able to tell from 
the above overview and from the introduction to the manual itself. The 
introduction will also tell you what you should already know before 
reading that manual. 

The Toolbox documentation is oriented toward the Pascal programmer. If 
you want to program in assembly language, you'll need to read the 
"Using QuickDraw from Assembly Language" section of the QuickDraw 
manual. There are also notes for assembly-language programmers in 
every Toolbox manual. 

Eventually the Operating System documentation will be structured the 
same as the Toolbox documentation, so all of the above will apply to 
it. For now, you're on your own with the Operating System Reference 
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Manual . 


Read the manual on putting together an application when you're ready to 
try something out. Currently the documentation doesn't include any 
sample programs, but you can get some through your software coordinator 
in the meantime. 
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Control Manager: A Toolbox unit that provides routines for creating 
and manipulating controls (such as buttons and check boxes). 

CoreEdit: A Toolbox unit that handles sophisticated text formatting 

and editing, including the use of different character fonts. 

Desk Manager: A Toolbox unit that supports the use of desk accessories 
from an application. 

Dialog Manager: A Toolbox unit that provides routines for implementing 
dialog boxes and the alert mechanism. 

event: A notification to an application program of some occurrence 

that the program must respond to. 

Event Manager: A Toolbox unit that allows your application program to 
monitor the user^s actions with the mouse, keyboard, and keypad. 

Font Manager: A Toolbox unit that supports the use of various 
character fonts when you draw text with QuickDraw. 

Menu Manager: A Toolbox unit that deals with setting up menus and 
letting the user choose from them. 

Operating System: The lowest-level software in the Macintosh. It 
communicates directly with the hardware and does basic tasks such as 
interrupt handling, memory management, and file I/O. 

QuickDraw: A Toolbox unit that allows you to perform highly complex 

graphics operations quickly and easily. 

resource: Data used by an application but stored separately from the 

application code. 

Resource Manager: The Toolbox unit that reads and writes resources. 

TextEdit: A Toolbox unit that supports the basic text entry and 

editing capabilities of a standard Macintosh application. 

Toolbox: Same as User Interface Toolbox. 

Toolbox Utilities: A Toolbox unit that lets you perform generally 
useful operations such as fixed-point arithmetic, string manipulation, 
and logical operations on bits. 

User Interface Toolbox: A set of routines and data types (divided into 
"units”) that help you implement the standard Macintosh user interface 
in your application. 

Window Manager: A Toolbox unit that provides routines for creating and 
manipulating windows. 
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ABSTRACT 

This manual describes the Segment Loader of the Macintosh Operating 
System, which lets you divide your application into several parts and 
have only some of them in memory at a time. 
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ABOUT THIS MANUAL 


This manual describes the Segment Loader, a new part of the Macintosh 
Operating System in ROM version 4. *** Eventually it will become part 

of a large manual describing the entire Operating System and Toolbox. 
*** The Segment Loader lets you divide your application into several 
parts and have only some of them in memory at a time. 

You should already be familiar with Lisa Pascal, the Macintosh 
Operating System's Memory Manager, the Finder, and the basic concepts 
behind the Resource Manager of the Macintosh User Interface Toolbox. 

The manual begins with an introduction to the Segment Loader and a 
description of the parameters that are stored in memory when an 
application is started up. Next, a section on using the Segment Loader 
introduces you to its routines and tells how they fit into the flow of 
your application. This is followed by the detailed descriptions of all 
Segment Loader routines, their parameters, calling protocol, effects, 
side effects, and so on. 

For advanced programmers, there's a section that discusses the jump 
table, explaining how the Segment Loader works internally. 

Finally, there's a summary of the Segment Loader routine calls, for 
quick reference, and a glossary of terms defined in this manual. 


ABOUT THE SEGMENT LOADER 


The Segment Loader allows you to divide the code of an application into 
several parts or segments . The Finder starts up an application by 
calling a Segment Loader routine that loads in the main segment (the 
one containing the main program) . Other segments are loaded in 
automatically when they're needed. Your application can call the 
Segment Loader to have these other segments removed from memory when 
they're no longer needed. 

The Segment Loader enables you to have programs larger than 32K bytes, 
the maximum size of a single segment. Also, any code that isn't 
executed often (such as code for printing hardcopy) need not occupy 
memory when it isn't being used, but can instead be in a separate 
segment that's brought in when needed. 

This mechanism may remind you of the resources of an application, which 
the Resource Manager of the User Interface Toolbox reads into memory 
when necessary. An application's segments are in fact themselves 
stored as resources; their resource type is 'CODE'. You can use the 
Resource Compiler to create these resources from your application code. 
A "loaded" segment has been read into memory by the Resource Manager 
and locked (so that it's neither relocatable nor purgeable) . When a 
segment is unloaded, it's made relocatable and purgeable. 
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Every segment has a name. If you do nothing about dividing your 
program into segments, it will consist of a single segment whose name 
is blank. Dividing your program into segments means specifying in your 
source file the beginning of each segment by name. The names are for 
your use only; they're not kept around after linking. 

( eye) 

If you do specify segment names, note that normally the 
main segment should have a blank name. The reason for 
this is that the intrinsic Pascal routines must be in the 
same segment as your main program, and the Linker puts 
those routines in the blank-named segment (so that the 
right thing will happen if you don't specify any segment 
names at all) . 


APPLICATION PARAMETERS 

When an application is started up, certain parameters are stored in 32 
bytes of memory just above the application's globals, as shown in 
Figure 1; these are called the application parameters . A5 points to 
the first of these parameters and may be used with positive offsets to 
access the others. 


32 


20 

16 

12 

8 

4 

A5-> 0 


high memory 


reserved for future use 


Finder information handle 
standard output 
standard input 
reserved for future use 
reserved for QuickDraw 


application 

parameter 

area 


application globals 


low memory 


Figure 1. Application Parameters 


( hand) 

For brevity, we'll say "A5" where we mean ’the location 
pointed to by A5". 

The "standard input" and "standard output" parameters indicate the main 
source of input and destination of output for the Macintosh. They are 
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usually 0, meaning the keyboard and the screen, respectively. 

The ’’Finder information handle” is a handle to information that the 
Finder provides to the application upon starting it up. For example, 
for a word processor it might be the name of the document to be worked 
on. *** The exact information will be described here when available. 
*** Pascal programmers can call the Segment Loader routine GetAppParms 
to get the Finder information handle. 

The other locations in the application parameter area are reserved for 
future use or for use by QuickDraw. 


USING THE SEGMENT LOADER __ 

This section introduces you to the Segment Loader routines and how they 
fit into the flow of an application program. The routines themselves 
are described in detail in the next section. 

The routine that applications will most commonly use is UnloadSeg, for 
unloading a particular segment when it's no longer needed. Another 
useful routine, GetAppParms, lets you get information about your 
application such as its name and the reference number for its 
resources. For applications started up in. the usual way by the Finder, 
GetAppParms also gives the Finder information handle that's stored 16 
bytes above A 5 . 

The main segment can unload other segments, but it can't get rid of 
itself; using the Chain routine, however, it can do something close to 
this. Chain starts up another application without disturbing the 
application heap. Thus the current application can let another 
application take over while still keeping its data around in the heap. 

The Segment Loader also provides a quick exit to the Finder that 
doesn't touch the stack, for applications needing it in emergency 
situations : Exi tToShell . 

Finally, there are two advanced routines that most applications will 
never use: Launch and LoadSeg. Launch is called by the Finder to 
start up an application; it's like Chain but doesn't retain the 
application heap. LoadSeg is called indirectly (via the jump table, as 
described later) to load segments when necessary — that is, whenever a 
routine in an unloaded segment is invoked. 


SEGMENT LOADER ROUTINES 

This section describes all the Segment Loader routines. Some of the 
routines are stack-based and so are shown in Pascal; for information on 
using them from assembly language, see ’’Using the Toolbox from Assembly 
Language” *** doesn't exist, but see QuickDraw manual ***. Other 
Segment Loader routines are register-based and are described similar to 
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the way the Operating System routines are described in the current 
Operating System manual. 


PROCEDURE UnloadSeg (routineAddr : Ptr) ; 

UnloadSeg unloads a segment, making it relocatable and purgeable; 
routineAddr is the address of any routine in the segment. The Segment 
Loader will reload the segment the next time one of the routines in it 
is called. It doesn't hurt to call UnloadSeg, because the segment 
won't actually be purged until the memory it occupies is needed. If 
you need the unloaded segment again before it's purged, the Segment 
Loader won't have to access the disk. 


PROCEDURE GetAppParms (VAR apName: Str255; VAR apRefNum: INTEGER; VAR 
apParam: Handle); 

GetAppParms returns information about the current application. It 
returns the application name in apName and the reference number for the 
application's resources in apRefNum. For applications started up in 
the usual way by the Finder, it returns the Finder information handle 
in apParam (as described earlier under " Application Parameters”). 

( hand) 

For applications started up with the Chain routine 
(below), the apParam parameter isn't useful. 


Chain {register-based} 

This routine starts an application up without doing anything to the 
application heap, so the current application can let another 
application take over while still keeping its data around in the heap. 
It configures memory for the sound and video buffers. A0 points to the 
following: 


where FILENAME is a pointer to the 
application's file name 

and MODE tells which sound buffer 
and video buffer to use (0 for 
standard) . 

6 


A0 > 0 1 


FILENAME 

(POINTER) 


MODE 


The sound and video buffers are constantly scanned by the Macintosh 
hardware to determine what sounds to emit from its speakers and what to 
display on its screen. (The video buffer is the bit image 
corresponding to the display screen.) Two of each type of buffer are 
available; Figure 2 shows where they're located. If you specify a MODE 
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value of 0, you get the standard or "primary" buffers; in this case, 
the application space begins where shown in Figure 2. Any positive 
MODE value causes the secondary sound buffer and primary video buffer 
to be used (which costs 1.5K of memory). Any negative MODE value 
causes the secondary sound buffer and secondary video buffer to be used 
(which costs 32K of memory). 


$20000 


$1 A700 
$1 A1 00 


$12700 


primary sound 


primary video 


secondary sound 


secondary video 


The application 
space normally 
ends here. 


Figure 2. Sound and Video Buffers 

Chain closes the resource file for any previous application and opens 
the resource file for the application being started* It also stores in 
memory the application parameters designating standard input and 
standard output* The application is started at its entry point, which 
causes the main segment to be loaded. 


PROCEDURE ExitToShell; 

ExitToShell provides an emergency exit for the application, without 
touching the stack. It simply launches the Finder (starts it up after 
freeing the storage occupied by the application heap; see Launch 
below) . 


Advanced Routines 


Launch {register-based} 

This routine is called by the Finder to start up an application and 
will rarely need to be called by an application itself. It's the same 
as the Chain routine (described above) except that it frees the storage 
occupied by the application heap and restores the heap to its original 
size. Also, the Finder provides startup information needed by the 
application; a handle to the information is located in the system heap 
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and is copied (as the "Finder information handle") into the application 
parameter area in memory. 

( hand) 

Launch preserves a special handle in the application heap 
which is used for accessing the scrap between 
applications • 


PROCEDURE LoadSeg (segID: INTEGER); 

LoadSeg is called indirectly via the jump table (as described in the 
following section) when the application calls a routine in an unloaded 
segment. It loads the segment having the given ID number, which was 
assigned by the Linker. If the segment isn't in memory, LoadSeg calls 
the Resource Manager to read it in. It changes the jump table entries 
for all the routines in the segment from the "unloaded" to the "loaded 
state and then invokes the routine that was called. 


THE JUMP TABLE 


This section describes how the Segment Loader works internally, and is 
included here for advanced programmers; you don't have to know about 
this to be able to use the common Segment Loader routines. 

The loading and unloading of segments is implemented through the 
application's jump table * Figure 3 shows the location of the jump 
table in memory for a typical application. 


(normally) $1A70Q 


high memory 



jump table 

A5 — > 

app 1 i cat i on parameters 

application globals 

stack grows downward 

stack 

toward heap 

heap grows upward 

| application heap 

toward stack 


the 

- application 
space 


system heap 


low memory 


Figure 3. The Application's Space in Memory 
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When the Linker encounters a call to a routine in another segment, it 
creates a jump table entry for the routine and addresses the entry with 
a positive offset from A5 . As described below, the jump table entry 
makes the connections necessary to invoke the routine. 

The jump table contains one 8-byte entry for every externally 
referenced routine in every segment; all the entries for a particular 
segment are stored contiguously. It refers to segments by ID numbers 
assigned by the Linker. When an application is started up, its jump 
table is read in from segment 0, a special segment created by the 
Linker for every executable file. Segment 0 contains the following: 


Number of bytes 
4 bytes 

4 bytes 

4 bytes 
4 bytes 
n bytes 


Contents 

"Above A5" size; size in bytes from A5 

to upper end of application space 

"Below A5" size; size in bytes of 

application globals 

Offset of jump table from A5 

Length of jump table in bytes 

Jump table 


For most applications, the offset of the jump table from A5 is 32, and 
the "above A5" size is 32 plus the length of the jump table. 


All the jump table entries for a particular segment indicate whether 
that segment is currently loaded or not, as illustrated in Figure 4. 



"unloaded" state 

"loaded" state 


routine offset 
(2 bytes) 


segment ID 
(2 bytes) 


move of segment 
ID onto stack 
(4 bytes) 


jump to address 
of routine 
(6 bytes) 


LoadSeg call 
(2 bytes) 



Figure 4. Format of a Jump Table Entry 

Initially, of course, the jump table entries are all in the "unloaded" 
state, which means they contain the following: 
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Number of bytes 
2 bytes 

4 bytes 

2 bytes 


Contents 

Offset of this routine from beginning of 
segment 

Instruction that moves the segment ID onto 
the stack for LoadSeg 
Trap that executes LoadSeg 


When a call to a routine in an unloaded segment is made, the code m 
the last six bytes of its jump table entry is executed. This code 
calls LoadSeg, which loads the segment into memory, transforms all of 
its jump table entries to the ’loaded state (shown below), and invokes 
the routine. 


Number of bytes Contents 

2 bytes Segment ID 

6 bytes Instruction that jumps to the address of the 

routine for which this is an entry 

LoadSeg invokes the routine by executing the instruction in the last 
six bytes of the jump table entry. Subsequent calls to the routine 
also execute this instruction. If UnloadSeg is called to unload the 
segment, it restores the jump table entries to their ’’unloaded state. 
Notice that whether the segment is loaded or unloaded, the last six 
bytes of the jump table entry are executed; the effect depends on the 

state of the entry at the time. 

To be able to set all the jump table entries for a segment to a 
particular state, LoadSeg and UnloadSeg need to know exactly where all 
the entries are located. They get this information from the segment 
header, four bytes at the beginning of the segment which contain the 
following: 

Number of bytes Contents 

2 bytes Offset of the first routine's entry from 

the beginning of the jump table 
2 bytes Number of entries for this segment 

As described above, segment 0 tells where the beginning of the jump 
table is located. 


SPECIFYING SEGMENTS IN YOUR SOURCE FILE 

*** This section will be moved into the next version of the manual 
entitled "Putting Together a Macintosh Application • *** 

You specify the beginning of a segment in your application s source 
file as follows: 

{ $S segname} 

where segname is the segment name, a sequence of up to eight 
characters. Normally you should give the main segment a blank name 
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For example, you might structure your program as follows: 

PROGRAM Shell; 

{ The USES statement and your LABEL, CONST, and VAR declarations 
will be here. } 

{$S Segl } 

{ The procedures and functions in Segl will be here. } 

{$S Seg2 } 

{ The procedures and functions in Seg2 will be here. } 

{$S } 

BEGIN 

{ The main program will be here. } 

END. 

You can specify the same segment name more than once; the routines will 
just be accumulated into that segment. To avoid problems when moving 
routines around in the source file, some programmers follow the 
practice of putting a segment name specification before every routine. 

( eye) 

Uppercase and lowercase letters ARE distinguished in 
segment names. For example, "Segl” and ”SEG1” are not 
equivalent names. 

If you don' t specify a segment name before the first routine in your 
file, the blank segment name will be assumed there. 

In assembly language, you specify the beginning of a segment with the 
following directive: 

.SEG 'segname' 


( eye) 

This requires version 12.2 of the Lisa Monitor. 

You can also specify what segment the routines in a particular file 
should be in by using the ChangeSeg program. For example, suppose you 
want to give your main segment a nonblank name (say, ” SegMain” ) ; you 
can't do this without using ChangeSeg, because the Linker puts the 
intrinsic Pascal routines in the blank—named segment, and they must be 
in the same segment as your main program. You can use ChangeSeg as 
shown below to tell the Linker to put the intrinsic Pascal routines, 
which are in Ob j :MacPasLib, in the segment named SegMain. 
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Prompt 

Monitor command line 
What file ? 

File to change: 

Map all Names ? (Y/N) 
New Seg name ? 


Response 
X {for X(ecute} 
ChangeSeg <ret> 

Ob j :MacPasLib <ret> 
Y {for Yes} 

SegMain <ret> 
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PROCEDURE UnloadSeg (routineAddr: Ptr); 

PROCEDURE GetAppParms (VAR apName: Str255; VAR apRefNum: INTEGER; 

VAR apParam: Handle); 


Chain {register-based} 

Input: A0 points to application's file name pointer followed by 

a word telling which sound and video buffers to use. 

Output: The application parameters for standard input and output. 

PROCEDURE Exi tToShell; 


Advanced Routines 

Launch {register-based} 

Input: A0 points to application's file name pointer followed by 

a word telling which sound and video buffers to use. 

Output: The application parameters — standard input and output 

and the Finder information handle. 

PROCEDURE LoadSeg (segID: INTEGER); 
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GLOSSARY 

application parameters: Information stored in 32 bytes of memory just 
above the application globals when an application is started up. 

jump table: A table that contains one entry for every routine in an 
application and is the means by which the loading and unloading of 
segments is implemented. 

main segment: The segment containing the main program. 

segment: One of several parts into which the code of an application 

may be divided. Not all segments need to be in memory at the same 
time. 


6/24/83 Rose 


CONFIDENTIAL 


/ SEGMENT/ SEGMENT . G 



MACINTOSH USER EDUCATION 


The Scrap Manager: A Programmer's Guide 


/SMGR/ SCRAP 


See Also: Macintosh User Interface Guidelines 

Macintosh Operating System Reference Manual 
QuickDraw: A Programmer's Guide 
The Resource Manager: A Programmer's Guide 
The Event Manager: A Programmer's Guide 
The Segment Loader: A Programmer's Guide 
The Desk Manager: A Programmer's Guide 
Putting Together a Macintosh Application 


Modification History: First Draft (ROM 7) 

Erratum Added 


C. Rose 10/21/83 
C. Rose 11/16/83 


ABSTRACT 

The Scrap Manager is a set of simple routines and data types that help 
Macintosh applications manipulate the Clipboard for cutting and pasting 
between applications, desk accessories, or an application and a desk 
accessory. This manual describes the Scrap Manager in detail. 


Erratum: 

The 'TEXT' type of data in the desk scrap is simply a series of ASCII 
characters, without a character count or an optional comment. If you 
want to know the count, you can get it by passing a NIL handle to the 
GetScrap function. 
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ABOUT THIS MANUAL 

This manual describes the Scrap Manager, a new part of the Macintosh 
User Interface Toolbox in ROM version 7. *** Eventually it will become 

part of a comprehensive manual describing the entire Toolbox* *** The 
Scrap Manager supports cutting and pasting between applications, desk 
accessories, or an application and a desk accessory* 

Like all documentation about Toolbox units, this manual assumes you're 
familiar with the Macintosh User Interface Guidelines, Lisa Pascal, and 
the Macintosh Operating System's Memory Manager. You should also be 
familiar with the followings 

- QuickDraw pictures 

- Resources, as discussed in the Resource Manager manual 

- The Toolbox Event Manager 

This manual is intended to serve the needs of both Pascal and 
assembly-language programmers* Information of interest only to 
assembly-language programmers is isolated and labeled so that Pascal 
programmers can conveniently skip it. 

The manual begins with an introduction to the Scrap Manager, an 
overview of the scrap that you manipulate with it, and a discussion of 
the types of data that the scrap may contain. 

Next, a section on using the Scrap Manager introduces its routines and 
tells how they fit into the flow of your application* This is followed 
by detailed descriptions of all Scrap Manager routines , their 
parameters, calling protocol, effects, side effects, and so on. 

Following these descriptions is a section that gives the exact format 
of the scrap, for those programmers who are interested; you don't have 
to read this section to be able to use the Scrap Manager routines. 

Finally, there's a summary of the Scrap Manager, for quick reference, 
followed by a glossary of terms used in this manual. 


ABOUT THE SCRAP MANAGER 

The Scrap Manager is a set of simple routines and data types that help 
Macintosh applications manipulate the desk scrap , which is where data 
that's cut (or copied) and pasted between applications is stored. An 
application can also use the desk scrap for storing data that's cut and 
pasted within the application, but usually it will have its own private 
scrap for this purpose. The format of the private scrap may be 
whatever the application likes, since no other application will use it. 
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From the user's point of view, there's a single place where all cut or 
copied data resides, and it's called the Clipboard* The Cut command 
deletes data from a document and places it in the Clipboard; the Copy 
command copies data into the Clipboard without deleting it from the 
document* The next Paste command —whether applied to the same document 
or another, in the same application or another— inserts the contents of 
the Clipboard at a specified place* An application that offers these 
editing commands will usually also have a special window for displaying 
the current Clipboard contents; it may show the Clipboard window at all 
times or only when requested (via the Show Clipboard and Hide Clipboard 
commands ) * 

The desk scrap is the vehicle for transferring data not only between 
two applications but also between an application and a desk accessory, 
or even between two desk accessories* Desk accessories that display 
text will commonly allow the text to be cut or copied* The user might, 
for example, use the Calculator accessory to do a calculation and then 
copy the result into a document* It's also possible for a desk 
accessory to allow something to be pasted into it* 

(hand) 

The Scrap Manager is optimized for transferring small 
amounts of data; attempts to transfer very large amounts 
of data may fail due to lack of memory* 

The nature of the data to be transferred varies according to the 
application* For example, for the Calculator or a word processor the 
data is text, and for a graphics application it's a picture* The 
amount of information retained about the data that's transferred also 
varies* Between two text applications, text can be cut and pasted 
without any loss of information; however, if the user of a graphics 
application cuts a picture consisting of text and then pastes it into a 
document created with a word processor, the text in the picture may not 
be editable in the word processor, or it may be editable but not look 
exactly the same as in the graphics application* The Scrap Manager 
allows for a variety of data types and provides a mechanism whereby 
applications have control over how much information is retained when 
data is transferred* 

Like any scrap, the desk scrap can be kept on the disk (in the scrap 
file ) if there's not enough room for it in memory* It may remain on 
the disk throughout the use of the application but must be read back 
into memory when the application terminates, since the user may then 
remove that disk and insert another* The Scrap Manager provides 
routines for writing the desk scrap to the disk and for reading it back 
into memory* 


OVERVIEW OF THE DESK SCRAP 

The desk scrap is initially located in the application heap, with a 
handle to it in low memory* When starting up an application, the 
Segment Loader temporarily moves the scrap out of the heap into the 
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stack, reinitializes the heap, and puts the scrap back in the heap. 

(See Figure 1.) For a short time while it does this, two copies of the 
scrap exist in the memory allocated for the stack and the heap; for 
this reason, the desk scrap cannot be bigger than half that amount of 
memory. 


Initially; 


low 

memory 


old 

heap 





Then; 



;rest of stack*' 


TVVIIIIPPPII 


KdSPscrapi 

F Xu^ddtdddddddd^Sti 


Finally: 



new 

heap 


Figure 1. The Desk Scrap at Application Start-up 

The application can get the size of the desk scrap by calling a Scrap 
Manager function named InfoScrap. An application concerned about 
whether there's room for the desk scrap in memory might be set up so 
that a small initial segment of the application is loaded in just to 
check out the scrap size. After a decision is made about whether to 
keep the scrap in memory or on the disk, the remaining segments can be 
loaded in as needed. 

There are certain disadvantages to keeping the desk scrap on the disk. 
The disk may be write-protected, may not have enough room for the 
scrap, or may be removed during use of the application. If the 
application can't write the scrap to the disk, it should put up an 
alert box Informing the user, who may want to abort the application at 
that point. 

The application must use the desk scrap for any Paste command given 
before the first Cut or Copy command (that is, the first since the 
application started up or since a desk accessory was deactivated); this 
requires copying the desk scrap to the private scrap, if any. Clearly 
the application must keep the contents of the desk scrap intact until 
the first Cut or Copy command is given. Thereafter it can ignore the 
desk scrap until a desk accessory is activated or the application is 
terminated; in either of these cases, it must copy its private scrap to 
the desk scrap. Thus whatever was last cut or copied within the 
application will be pasted if a Paste command is then given in a desk 
accessory or in the next application. 
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1. User enters word processor after cutting a picture in the previous application. 


empty 

private scrap 

2. User gives Paste co m ma n d in word pro c e ss or (without a previous Cut or Copy). 


picture 


desk scrap 


picture 


converted 

picture 


-> pasted where specified 


desk scrap 


private scrap 


3a. User cuts text in word pr o cess or . 


picture 


text 


desk scrap private scrap 

3b. User leaves word p ro cessor. 



OR: 


3. User leaves word pro cesso r 
(without a previous Cut or Copy). 


picture 


converted 

picture 


desk scrap 


private scrap 


desk scrap private scrap 

Figure 2. Interaction between Scraps 


Figure 2 illustrates how the interaction between the desk scrap and the 
application's private scrap might occur when the user gives a Paste 
command in a word processor after cutting a picture in a graphics 
application. As the picture that was cut gets copied to the private 
scrap, it's converted to the format of that scrap. If the user leaves 
the word processor after cutting or copying text, the text first goes 
into the private scrap and then gets copied to the desk scrap. On the 
other hand, if the user never gives a Cut or Copy command, the 
application won't copy the private scrap to the desk scrap, so the 
original contents of the desk scrap will be retained. 


Suppose the word processor in Figure 2 displays the contents of the 
Clipboard. Normally it will display its private scrap; however, to 
show the Clipboard contents at any time before step 2, it will have to 
display the desk scrap instead, or first copy the desk scrap to its 
private scrap. It can instead simply copy the desk scrap to its 
private scrap at start-up (step 1), so that showing the Clipboard 
contents will always mean displaying the private scrap. 

A similar scheme to that shown in Figure 2 must be followed when the 
user reenters an application after using a desk accesory, since the 
user may have done cutting or copying in the accessory. The 
application can in fact check whether any such cutting or copying was 
done, by looking at a count that's returned by InfoScrap. If this 
count changes during use of the desk accessory, it means the contents 
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of the desk scrap have changed; the application will have to copy the 
desk scrap to the private scrap, if any, and update the contents of the 
Clipboard window, if there is one and if it's visible. If the count 
returned by InfoScrap hasn't changed, however, the application won't 
have to take either of these actions* 

If the application encounters problems in trying to copy one scrap to 
another, it should alert the user. The desk scrap may be too large to 
copy to the private scrap, in which case the user may want to leave the 
application or just proceed with an empty Clipboard. If the private 
scrap is too large to copy to the desk scrap, either because it's 
disk— based and too large to copy into memory or because it exceeds the 
maximum size allowed for the desk scrap, the user may want to stay in 
the application and cut or copy something smaller. 


DESK SCRAP DATA TYPES 


From the user's point of view there can be only one thing in the 
Clipboard at a time, but internally there may be more than one data 
item in the desk scrap, each representing the same Clipboard contents 
in a different form. For example, text cut with a word processor may 
be stored in the desk scrap both as text and as a QuickDraw picture. 

Desk scrap data types are like resource types. As defined in the 
Resource Manager, their Pascal type is as follows: 

TYPE Res Type ° PACKED ARRAY [1..4] OF CHAR; 

The Scrap Manager recognizes two standard types of data in the desk 
scrap. 


— 'TEXT': a series of ASCII characters, preceded by a long word 
containing the number of characters and optionally followed by a 
comment, as described below. 

- 'PICT': a QuickDraw picture, which is a saved sequence of drawing 
commands that can be played back with the DrawPicture command and 
may Include picture comments. (See the QuickDraw manual for 
details.) 

Applications must write at least one of these standard types of data to 
the desk scrap and must be able to read both types. Most applications 
will prefer one of these types over the other; for example, a word 
processor prefers text while a graphics application prefers pictures. 

An application should at least write its preferred standard type of 
data to the desk scrap, and ideally will write both types (to pass the 
most information possible on to the receiving application, which may 
prefer the other type). 

An application reading the desk scrap will look for its preferred data 
type. If its preferred type isn't there, or if it's there but was 
written by an application having a different preferred type, some 
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information may be’ lost in the transfer process. For example, consider 
the user 'of a graphics application who cuts a picture consisting of 
text and then goes into a word processor and pastes it (as illustrated 
in Figure 3). 

- If the graphics application writes only its preferred data type, 
picture, to the desk scrap (like application A in Figure 3), the 
text in the picture will not be editable in the word processor, 
because it will be seen as just a series of drawing commands and 
not a sequence of characters. 

- On the other hand, if the graphics application takes the trouble 
of recognizing which characters have been drawn in the picture, 
and also writes them out to the desk scrap as text (like 
application B in Figure 3), the word processor will be able to 
treat them like any text, with editing or whatever* In this case, 
however, any part of the picture that isn’t text will be lost. 


Graphics Application A 


Word P rocessor 


picture 
consisting 
of text 


Cut 


^(picture 


Paste 


desk scrap 







Graphics Application B Word Processor 



Figure 3. Inter-Application Cutting and Pasting 

In addition to the two standard data types, the desk scrap may also 
contain application-specific types of data. If several applications 
are to support the transfer of a private type of data, each one will 
write and read that type—clearly its preferred type— but still must 
write at least one of the standard types and be able to read both 
standard types. 

(eye) 

There should never be more than one of each type of data 
in the desk scrap at a time. 

The order in which data is written to the desk scrap is important: the 
application should write out the different types in order of 
preference. For example, if it’s a word processor that writes out a 
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private type of data as well as text and pictures, it should do so in 
that order. 

Since the size of the desk scrap is limited, it may be too costly to 
write out both an application-specific type of data and one (or both) 
of the standard types. If so, the comments that can accompany text or 
pictures might be useful. Instead of creating an application-specific 
type , you may be able to encode additional information in these 
comments. For example, instead of having a data type that consists of 
text and formatting information combined in an application-specific 
way , you can encode the formatting information in the text comment . 
Applications that are to process that information can do so, while 
others can ignore it. 

A text comment follows the last character in the text and must begin 
with the application ID, a four-character sequence that you choose to 
uniquely identify your application when you build it. *** (This ID 
will be discussed further in a future revision of the manual "Putting 
Together a Macintosh Application".) *** Any data that you like can 
follow the application ID. 

As described in the QuickDraw manual, picture comments may be stored in 
the definition of a picture with the QuickDraw procedure PicComment. 

The DrawPicture procedure passes any such comments to a special routine 
set up by the application for that purpose. 


USING THE SCRAP MANAGER 

This section discusses how the Scrap Manager routines fit into the 
general flow of an application program and gives you an idea of which 
ones you'll need to use. The routines themselves are described in 
detail in the next section. 

The application should inquire as early as possible about the size of 
the desk scrap to determine whether there will be enough room for 
itself and the scrap to coexist in the heap; it can do so by calling 
the InfoScrap function. If there won't be enough room for the desk 
scrap in the heap, the application should call the UnloadScrap 
procedure to write the scrap from memory onto the disk. InfoScrap also 
provides a handle to the desk scrap if it's in memory, its file name on 
the disk, and a count that's useful for testing whether the contents of 
the desk scrap have changed during the use of a desk accessory. 

If a Paste command is given before the first Cut or Copy command after 
the application starts up, the application must copy the contents of 
the desk scrap to its private scrap, if any. It can do this either 
upon starting up or when the Paste command that needs to use the desk 
scrap is given. The latter method usually suffices, but applications 
that support display of the Clipboard will benefit from copying the 
desk scrap at start-up. The Scrap Manager routine that gets data from 
the desk scrap is called Get Scrap. 
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When the user gives a command that terminates the application, the 
application's private scrap will usually have to be copied to the desk 
scrap* If the desk scrap is on the disk, it must first be read into 
memory with the LoadScrap function* The application must call 
ZeroScrap to reinitialize the desk scrap and clear its previous 
contents, and then PutScrap to put data in the scrap. 

(eye) 

Do not copy the private scrap to the desk scrap unless a 

Cut or Copy command was given that changed the contents 

of the Clipboard. 

The same kind of scrap interaction that occurs at application start-up 
also applies to returning to the application from a desk accessory 
(that is, an activate event that activates an application window after 
deactivating a system window). Similarly, the interaction when an 
application terminates also applies to accessing a desk accessory from 
the application (as reported by an activate event that deactivates an 
application window and activates a system window). Mote, however, that 
a desk accessory shouldn't concern itself with writing or reading the 
desk scrap from the disk. 

Cutting and pasting between two desk accessories follows an analogous 
scenario. As described in the Desk Manager manual, the way a desk 
accessory learns it must respond to an editing command is that its 
control routine receives a message telling it to perform the command; 
the application needs to call the Desk Manager function SystemEdit to 
make this happen. 


SCRAP MANAGER ROUTINES 

This section describes all the Scrap Manager routines. They are 
presented in their Pascal form; for information on using them from 
assembly language, see "Using the Toolbox from Assembly Language" *** 
for now, see "Using QuickDraw from Assembly Language" in the QuickDraw 
manual ***, 


Getting Scrap Information 


FUNCTION InfoScrap : PScrapStuff; 

InfoScrap returns a pointer to information about the desk scrap. The 
PScrapStuff data type is defined as follows: 
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TYPE PScrapStuff 
Scrap Stuff 


“ScrapStuf f ; 

RECORD 

scrapSize: Longlnt; 

scrapHandle: Handle; 
scrapCount : INTEGER; 
scrapState: INTEGER; 
scrapName : StringPtr 

END; 


ScrapSize is the size of the entire desk scrap in bytes. ScrapHandle 
is a handle to the scrap if it's in memory, or NIL if not. ScrapCount 
is a count that changes every time ZeroScrap is called and is useful 
for testing whether the contents of the desk scrap have changed during 
the use of a desk accessory (see ZeroScrap under "Writing to the 
Scrap", below). ScrapState is positive if the desk scrap is in memory 
or 0 if it's on the disk. ScrapName is a pointer to the name of the 
scrap file, usually DeskScrap. 


Keeping the Scrap on the Disk 


FUNCTION UnloadScrap : Longlnt; 

Unload Scrap writes the desk scrap from memory to the scrap file. If 
the desk scrap is already on the disk, it does nothing. If no error 
occurs, UnloadScrap returns 0; otherwise, it returns an appropriate 
Operating System error code. 


Assembly— language note i The macro you invoke to call 
UnloadScrap from assembly language is named JUnlodeScrap. 


FUNCTION LoadScrap : Longlnt; 

LoadScrap reads the desk scrap from the scrap file into memory. If the 
desk scrap is already in memory, it does nothing. If no error occurs, 
LoadScrap returns 0; otherwise, it returns an appropriate Operating 
System error code. 


Assembly— language note : The macro you invoke to call LoadScrap 
from assembly language is named _Lode Scrap. 
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Reading from the Scrap 


FUNCTION GetScrap (hDests Handle; the Types ResType; VAR offset: 

Longlnt) : Longlnt; 

GetScrap reads the data of type the Type from the desk scrap (whether in 
memory or on the disk), makes a copy of it in memory, and sets up the 
hDest handle to point to the copy* Usually you'll pass an empty handle 
in hDest. In the offset parameter, GetScrap returns the location of 
the data as an offset (in bytes) from the beginning of the desk scrap. 
If no error occurs, the function result is the length of the data in 
bytes; otherwise, it's either an appropriate Operating System error 
code (which will be negative) or the following predefined constants 

CONST noTypeErr = —102; (there's no data of the requested type} 
For example, given an empty handle declared as 

VAR pHndls PicHandle 
you can make the following calls s 

Get Scrap ( POINTER( ORD( pHndl ) ) , 'PICT' ) ; 

DrawPicture(pRndl ) ; 

Your application should pass its preferred data type to GetScrap. If 
it doesn't prefer one data type over any other, it should try getting 
different types until the offset returned is 0. An offset of 0 means 
that data was the first to be written out and so should be the 
preferred type of the application that wrote it. 

If you pass NIL in hDest, GetScrap will not read in the data. This is 
useful if you want to be sure the data is there before allocating space 
for its handle, or if you just want to know the size of the data. If 
there isn't enough room in memory for a copy of the data, as may be the 
case for a complicated picture, you can customize QuickDraw's picture 
retrieval so that DrawPicture will read from the picture directly from 
the scrap file. (QuickDraw also lets you customize how pictures are 
saved so you can save them in a file; see the QuickDraw manual for 
details about customizing.) 


Writing to the Scrap 


FUNCTION ZeroScrap s Longlnt; 

ZeroScrap initializes the desk scrap, clearing its contents; you must 
call it before the first time you call PutScrap (described below). If 
no error occurs, ZeroScrap returns 0; otherwise, it returns an 
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appropriate Operating System error code. 

ZeroScrap also changes the scrapCount field of the record of 
information provided by InfoScrap. This is useful for testing whether 
the contents of the desk scrap have changed during the use of a desk 
accessory. The application can save the value of the scrapCount field 
when one of its windows is deactivated and a system window is 
activated. Then, each time through its event loop, it can check to see 
whether the value of the field has changed. If so, it means the desk 
accessory called ZeroScrap (and, presumably, PutScrap) and thus changed 
the contents of the desk scrap. 


FUNCTION PutScrap (length: Longlnt; theType: ResType; source: Ptr) : 
Longlnt; 

PutScrap writes the data pointed to by the source parameter to the desk 
scrap (whether in memory or on the disk). The length parameter 
indicates the number of bytes to write, and theType is the data type 
(which should be different from' the type of any data already in the 
desk scrap). If no error occurs, the function result is 0; otherwise, 
it's an appropriate Operating System error code. 

(eye) 

Don't forget to call ZeroScrap (above) to clear the scrap 
before your first call to PutScrap. 


FORMAT OF THE DESK SCRAP 


In general, the desk scrap consists of a series of data items that have 
the following format : 


Number of bytes 
4 bytes 
4 bytes 
n bytes 


Contents 

Type (a sequence of four characters) 
Length of following data in bytes 
Data; n must be even (if the above length 
is odd, include an extra byte) 


The standard types are 'TEXT' and 'PICT'. You may use any other 
four-character sequence for types specific to your application. 


The format of the data for the 'TEXT' type is as follows: 


Number of bytes 
4 bytes 
n bytes 
m bytes 


Contents 

Number of characters in the text 
The characters in the text 
Optional comment: the 4-byte application 
ID followed by any information desired 


The data for the 'PICT' type is a QuickDraw picture, which consists of 
the size of the picture in bytes, the picture frame, and the picture 
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definition data (which may include picture comments). 
QuickDraw manual for details. 
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SUMMARY OF THE SCRAP MANAGER 


Constants 


CONST noTypeErr ■ -102; {there's no data of the requested type} 


Data Structures 


TYPE PScrapStuff ■ ~ScrapStuff; 

ScrapStuff =* RECORD 

scrapSize : 
scrapHandle : 
scrapCount : 
scrapState: 
scrap Name : 

END; 


Longlnt ; 
Handle ; 
INTEGER; 
INTEGER; 
String Ptr 


Routines 


Getting Scrap Information 
FUNCTION InfoScrap : PScrapStuff; 

Keeping the Scrap on the Disk 

FUNCTION UnloadScrap : Longlnt; 
FUNCTION LoadScrap : Longlnt; 


Reading from the Scrap 

FUNCTION GetScrap (hDest: Handle; theType: Res Type; VAR offset: Longlnt) 
: Longlnt; 


Writing to the Scrap 
FUNCTION ZeroScrap : Longlnt; 

FUNCTION PutScrap (length: Longlnt; theType: ResType; source: Ptr) : 

Longlnt; 
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Assembly-Language Information 


Constants 


noTypeErr .EQU -102 ;there's no data of the requested type 


Scrap Information Data Structure 


scrapSize 

scrapHandle 

scrapCount 

scrapState 

scrapName 


Size of desk scrap in bytes *** (currently named 
scrap Info) *** 

Handle to desk scrap in memory 
Count changed by Zero Scrap 

Positive if desk scrap in memory, 0 if on disk 
Pointer to name of scrap file 


Special Macro Names 

Routine name Macro name 

Load Scrap _Lode Scrap 

Unload Scrap _Unlode Scrap 
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application ID: A four-character sequence that you choose to identify 
your application when you you build it. 

desk scrap: The place in memory or on the disk where data that's cut 
(or copied) and pasted between applications is stored. 

scrap file: The file containing the desk scrap. 
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ABOUT THIS MANUAL 


This manual describes the Toolbox Utilities, a set of routines and data 
types in the User Interface Toolbox that perform generally useful 
operations such as fixed-point arithmetic, string manipulation, and 
logical operations on bits. *** Eventually it will become part of a 
comprehensive manual describing the entire Toolbox and Operating 
System. *** 

You should already be familiar with Lisa Pascal. Depending on which 
Toolbox Utilities you're interested in using, you may also need to know 
about the Macintosh Operating System's Memory Manager, the Resource 
Manager, and the basic concepts and structures behind QuickDraw. 

This manual begins with a discussion of fixed-point numbers. This is 
followed by the detailed descriptions of all Toolbox Utility procedures 
and functions, their parameters, calling protocol, effects, side 
effects, and so on. Finally, there's a summary of the Toolbox 
Utilities, for quick reference, followed by a glossary of terms used in 
this manual. *** The glossary has only two entries, but eventually it 
will be merged with the glossaries from the other Toolbox and Operating 
System documentation. *** 


FIXED-POINT NUMBERS 


The Toolbox Utilities include routines for operating on fixed-point 
numbers . A fixed-point number is a 32-bit quantity containing an 
integer part in the high-order word and a fractional part in the 
low-order word (see Figure 1). Since these numbers occupy the same 
number of bits as long integers, they could be given the data type 
Longlnt; however, to reflect the different interpretation the bits have 
as fixed-point numbers, the following data type is defined in the 
Toolbox Utilities: 

TYPE Fixed = Longlnt; 
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Figure 1. Fixed-Point Numbers 
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As described in the following section, there are Toolbox Utility 
routines for converting an integer numerator and denominator into a 
fixed-point number, multiplying two fixed-point numbers, and rounding a 
fixed-point number to the nearest integer. You can also use the 
general-purpose function HiWord (or LoWord) to extract the integer (or 
fractional) part of a fixed -point number. 


TOOLBOX UTILITY ROUTINES 


This section describes all the Toolbox Utility procedures and 
functions. They're presented in their Pascal form; for information on 
using them from assembly language, see "Using the Toolbox from Assembly 
Language" *** doesn't exist, but see "Using QuickDraw from Assembly 
Language" in the QuickDraw manual ***. 


Fixed-Point Arithmetic 


See also HiWord and LoWord under "Other Operations on Long Integers" 
below. 


FUNCTION FixRatio (numerator , denominator : INTEGER) : Fixed; 

FixRatio returns the fixed-point number having the given numerator and 
denominator (either of which may be any signed integer). 

FUNCTION FixMul (a,b: Fixed) : Fixed; 

FixMul multiplies the given fixed-point numbers and returns the result. 


FUNCTION FixRound (x: Fixed) : INTEGER; 

FixRound rounds the given fixed-point number to the nearest integer and 
returns the result. 


String Manipulation 

These routines use the StringHandle data type, which is defined in the 
Toolbox Utilities as follows: 

TYPE StringPtr - ~Str255; 

StringHandle = '“StringPtr; 
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FUNCTION NewString (s: Str255) : StringHandle; 

NewString allocates the string specified by s as a relocatable object 
on the heap and returns a handle to it. 


PROCEDURE SetString (h: StringHandle; s: Str255); 

SetString sets the string whose handle is passed in h to the string 
specified by s. 


FUNCTION GetString (stringID: INTEGER) : StringHandle; 

GetString returns a StringHandle to the string having the given 
resource ID, reading it from the resource file if necessary. It calls 
the Resource Manager function GetResource( 'STR ', stringID). 


Byte Manipulation 


FUNCTION Munger (h: Handle; offset: Longlnt; ptrl: Ptr; lenl : Longlnt; 
ptr2: Ptr; len2: Longlnt) : Longlnt; 

*** There's currently no Pascal interface to this routine; declare it 
as EXTERNAL in your program* *** 

Munger manipulates bytes in the string of bytes (the "destination 
string") to which h is a handle* The offset parameter specifies a byte 
offset into the destination string* The exact nature of the operation 
done by Munger depends on the values of the remaining parameters, two 
pointer/length pairs. In general, (ptrl, lenl) defines a substring to 
be replaced by the second substring (ptr2,len2). If these four 
parameters are all positive and nonzero, Munger looks for (ptrl, lenl) 
in the destination string, starting from the given offset and ending at 
the end of the string; the first occurrence it finds is replaced by 
(ptr2,len2), and the offset at which the replacement occurred is 
returned. Figure 2 illustrates this; the bytes represent ASCII 
characters as shown* 
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Given: 


offset = 4 


(raster pointer 


iQiDSBDIDiiliiiDi 


the destination string 


Itihlel the substring to be replaced (ptrl, lenl) 


lenl = 3 


Ien2 = 2 


the replacement substring (ptr2,len2) 


Mmger(h,offset,ptr1 , Ien1,ptr2, Ien2) yields: 


returned value = 8 


master pointer 


Figure 2. Munger Function 

Different operations occur if any of the pointers or lengths is 0: 

- If ptrl is 0, the substring of length lenl starting at the given 
offset is replaced by (ptr2,len2)* If lenl is negative, the 
substring from the given offset to the end of the destination 
string is replaced by (ptr2,len2). 

- If lenl is 0, the substring (ptr2,len2) is simply inserted at the 
given offset* 

- If ptr2 is 0, the destination string isn’t changed; Munger just 
returns the offset at which it found (ptrl, lenl)* 

- If len2 is 0, the replacement substring is empty, so (ptrl, lenl) 
is deleted rather than replaced* 

Munger returns the offset at which the operation occurred — whether 
replacement, insertion, deletion, or just location of a substring* It 
returns a negative value if it can't find (ptrl, lenl) in the 
destination string* 


(eye) 


Be careful not to specify an offset that's greater than 
the length of the destination string, or unpredictable 
things may happen. 
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Bit Manipulation 

These routines manipulate a bit in data pointed to by a given pointer* 

A bit number indicates which bit; it starts at 0 for the high-order bit 
of the first byte pointed to and may be any positive long integer 
specifying an offset from that bit (see Figure 3). 


BitTst (thisPtr,?) tests this bit 



Figure 3. Bit Numbering for Utility Routines 


(hand) 

Note that this bit numbering is the opposite of the 
MC68000 bit numbering. 


FUNCTION BitTst (bytePtr: Ptr; bitNum: Longlnt) : BOOLEAN; 

BitTst tests whether a given bit is set and returns TRUE if so or FALSE 
if not. The bit is specified by bitNum, an offset from the high— order 
bit of the byte pointed to by bytePtr. 


PROCEDURE BitSet (bytePtr: Ptr; bitNum: Longlnt); 

BitSet sets the bit specified by bitNum, an offset from the high-order 
bit of the byte pointed to by bytePtr. 


PROCEDURE BitClr (bytePtr: Ptr; bitNum: Longlnt); 

BitSet clears the bit specified by bitNum, an offset from the high- 
order bit of the byte pointed to by bytePtr. 
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Logical Operations 


FUNCTION BitAnd (longl ,long2 : Longlnt) : Longlnt; 

Bit And returns the result of the AND logical operation on the bits 
comprising the given long integers (longl AND long2). 


FUNCTION BitOr (longl ,long2 : Longlnt) : Longlnt; 

BitOr returns the result of the OR logical operation on the bits 
comprising given long integers (longl OR long2). 


FUNCTION BitXor (longl ,long2 : Longlnt) : Longlnt; 

BitXor returns the result of the XOR logical operation on the bits 
comprising the given long integers (longl XOR long2). 


FUNCTION BitNot (long: Longlnt) : Longlnt; 

BitXor returns the result of the NOT logical operation on the bits 
comprising the given long integer. 


FUNCTION BitShift (long: Longlnt; count: INTEGER) : Longlnt; 

BitShift logically shifts the bits of the given long integer. Count 
specifies the direction and extent of the shift, and is taken modulo 
31. If count is positive, BitShift shifts that many positions to the 
left; if count is negative, it shifts to the right. Zeros are shifted 
into empty positions at either end. 


Other Operations on Long Integers 




FUNCTION Hi Word (x: Longlnt) : INTEGER; 

HiWord returns the high-order word of the given long integer. One use 
of this function is to extract the integer part of a fixed-point 
number. 


FUNCTION LoWord (x: Longlnt) : INTEGER; 

LoWord returns the low-order word of the given long integer. One use 
of this function is to extract the fractional part of a fixed-point 
number. 




1/4/84 Rose 


CONFIDENTIAL 


/TOOLUTIL/UTIL . R 



TOOLBOX UTILITY ROUTINES 9 


PROCEDURE LongMul (a,b: Longlnt; VAR dest: Int64Bit); 

LongMul multiplies the given long integers and returns the result in 
dest, which has the following data type: 

TYPE Int64Bit = RECORD 

hiLong: Longlnt; 
loLong: Longlnt 
END; 


Graphics Utilities 


FUNCTION Getlcon (iconID: INTEGER) : Handle; 

Getlcon returns a handle to the icon having the given resource ID, 
reading it from the resource file if necessary. It calls the Resource 
Manager function GetResourceC 'ICON' , iconID). 

PROCEDURE Plotlcon (theRect: Rect; thelcon: Handle); 

*** There's currently no Pascal interface to this routine; declare it 
as EXTERNAL in your program. *** 

Plotlcon draws the icon whose handle is thelcon in the rectangle 
theRect, which is in the local coordinates of the current grafPort. It 
calls the QuickDraw procedure CopyBits and uses the srcCopy transfer 
mode. (You must have initialized QuickDraw before calling Plotlcon.) 


FUNCTION GetPattern (patID: INTEGER) : PatHandle; 

Getlcon returns a handle to the pattern having the given resource ID, 
reading it from the resource file if necessary. It calls the Resource 
Manager function GetResourceC 'PAT ', patID). The PatHandle data type is 
*** not yet, but soon will be *** defined in the Toolbox Utilities as 

follows: 


TYPE PatPtr = "Pattern; 
PatHandle = "PatPtr; 


FUNCTION GetCursor (cursorlD: INTEGER) : CursHandle; 

Getlcon returns a handle to the cursor having the given resource ID, 
reading it from the resource file if necessary. It calls the Resource 
Manager function GetResourceC 'CURS' , cursorlD). The CursHandle data 
type is *** not yet, but soon will be *** defined in the Toolbox 
Utilities as follows: 
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TYPE CursPtr = ^Cursor; 
CursHandle = '“CursPtr; 


PROCEDURE ShieldCursor (left , top .right , bottom: INTEGER); 

Given the global coordinates of a rectangle, ShieldCursor removes the 
cursor from the screen if the cursor and the rectangle intersect. 


FUNCTION GetPicture (picturelD: INTEGER) : PicHandle; 

GetPicture returns a handle to the picture having the given resource 
ID, reading it from the resource file if necessary. It calls the 
Resource Manager function GetResource( 'PICT' .picturelD). The PicHandle 
data type is defined in QuickDraw. 
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SUMMARY OF THE TOOLBOX UTILITIES 

TYPE Fixed = Longlnt; 

Int64Bit = RECORD 

hiLong: Longlnt; 

1 oLong : Longlnt 
END; 

StringPtr = ~Str255; 

StringHandle = 'StringPtr; 

CursPtr = '"Cursor; 

CursHandle = '“CursPtr; 

PatPtr = ^Pattern; 

PatHandle = ~PatPtr; 

Fixed-Point Arithmetic 

FUNCTION FixRatio (numerator .denominator : INTEGER) : Fixed; 
FUNCTION FixMul (a.b: Fixed) : Fixed; 

FUNCTION FixRound (x: Fixed) : INTEGER; 


String Manipulation 

FUNCTION NewString (s: Str255) : StringHandle; 
PROCEDURE SetString (h: StringHandle; s: Str255); 
FUNCTION GetString (string ID: INTEGER) : StringHandle; 


Byte Manipulation 

FUNCTION Munger (h: Handle; offset: Longlnt; ptrl : Ptr; lenl : Longlnt; 
ptr2: Ptr; len2: Longlnt) : Longlnt; 


Bit Manipulation 

FUNCTION BitTst (bytePtr: Ptr; bitNum: Longlnt) : BOOLEAN; 
PROCEDURE BitSet (bytePtr: Ptr; bitNum: Longlnt); 

PROCEDURE BitClr (bytePtr: Ptr; bitNum: Longlnt); 
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Logical Operations 


FUNCTION Bit And 
FUNCTION BitOr 
FUNCTION BitXor 
FUNCTION BitNot 
FUNCTION Bit Shi ft 


(longl ,long2: Longlnt) : Longlnt; 

(longl ,long2: Longlnt) : Longlnt; 

(longl ,long2: Longlnt) : Longlnt; 

(long: Longlnt) : Longlnt; 

(long: Longlnt; count: INTEGER) : Longlnt; 


Other Operations on Long Integers 

FUNCTION Hi Word (x: Longlnt) : INTEGER; 

FUNCTION LoWord (x: Longlnt) : INTEGER; 

PROCEDURE LongMul (a,b: Longlnt; VAR dest: Int64Bit); 


Graphics Utilities 

FUNCTION Getlcon (iconID: INTEGER) : Handle; 

PROCEDURE Plotlcon (theRect: Rect; thelcon: Handle); 
FUNCTION GetPattern (patID: INTEGER) : PatHandle; 
FUNCTION GetCursor (cursorlD: INTEGER) : CursHandle; 
PROCEDURE ShieldCursor (left, top, right, bottom: INTEGER); 
FUNCTION GetPicture (picturelD: INTEGER) : PicHandle; 
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fixed-point number: A 32— bit quantity containing an integer part in 
the high-order word and a fractional part in the low-order word. 

icon: A 32— by— 32 bit image that represents an object, concept, or 
message. 
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page) at 10460 Bandley Drive M/S 3-G, Cupertino CA 95014. 

Mark up a copy of the manual or note your remarks separately. 

(Well return your marked-up copy if you like.) 


Thanks for your helpl 
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ABSTRACT 


One of the major factors in making a system pleasant and easy to use is 
the system' s consistency. This specification's purpose is to set down 
our agreements about the way programs will interact with users, so that 
we have a common method for dealing with interface problems , and so that 
all software written for the Macintosh computer (in-house or by outside 
vendors) will be consistent with respect to the issues discussed here. 
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INTRODUCTION 


Macintosh is intended to be the first mass— market personal computer » 

It is designed to appeal to an audience of non-programmers, including 
people who have traditionally feared and distrusted computers. To 
achieve this goal, Macintosh must be friendly. The system must, once 
and for all, dispel any notion that computers are difficult to use. 

Two key ingredients combine in making a system easy to use: 
familiarity and consistency . 

Familiarity means that the conceptual underpinnings of a system are 
based on premises or procedures our users already know and employ. 

Most Macintosh applications are oriented towards common tasks: 
writing, graphics and paste-up work, ledger sheet arithmetic, chart and 
graph preparation, and sorting and filing. The actual environment for 
performing these tasks already exists in people's offices and homes; we 
mimic that environment to an extent which makes users comfortable with 
the system. Extensive use of graphics plays an important part in the 
creation of a familiar and intuitive environment. 

Consistency means a uniform way of approaching tasks across 
applications. For example, when users learn how to insert text into a 
document, or how to select a column of figures in one application, they 
should be able to take that knowledge with them into other applications 
and build upon it. Uniformity and consistency in the user interface 
reduces frustration and makes a user more amenable to trying new 
techniques and new software to solve problems. 

Consistency and familiarity are by no means orthogonal concepts. 
Familiar models should be used in a consistent manner to avoid 
confusion, and consistency should not lead to unfamiliar behavior. 


Software Developers ' Responsibility 

Preservation of a truly consistent working environment requires some 
deliberate and conscious effort on the part of applications 
programmers. 

If Macintosh is to be successful as a truly mass-market personal 
computer, software developers must maintain consistency throughout 
applications by conforming to a common user interface. 

(hand) 

It is the responsibility of everyone who writes software 
for Macintosh to preserve the integrity of the system. 

Years of software development, testing, and research have gone into the 
definition of the Macintosh user interface. The mechanisms outlined in 
this document have been shown to be well— suited for a variety of 
applications and tasks. If your application requires approaches not 
specified in this document, we urge you to build your schemes on top of 
existing ones and avoid incompatibility at all costs. 
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Macintosh s Commitment . 

On many other computers, since little or no user interface aids are 
built in, each applications programmer invents a new and original 
interface for each program — which leads to hundreds of different, 
conflicting, and confusing interfaces. 

We hope to avoid this situation on Macintosh by building tools for a 
versatile, well-tested user interface and placing them in ROM to be 
used by all applications programs. There's no strict requirement that 
an applications program must use all or any of the supplied interface 
tools; but programmers who create their own interface do so at the 
expense of their own development time, the user's data space, and the 
entire system's coherency. 

Consistency in the user interface is most important in three areas: 

- Data selection and editing; 

- Command invocation; 

- Performance of common system-wide functions. 

These are common to all applications. But each application also has 
its unique requirements, all of which we cannot forsee. To accommodate 
each application's specific needs, most of the features of the user 
interface are extensible: a programmer can "customize” the appearance 
or function of a common interface feature to suit the application. 

Macintosh system software is designed to make the implementation of the 
user interface as simple as possible for the programmer. Most of the 
recommended user interface features outlined below are implemented with 
simple calls to the User Interface ToolBox or the Operating System. 

The substantial documentation available for those packages should serve 
as an introduction to implementing the user interface described in this 
document • 


About Modes ^ 

"A good man will prefer that mode, by which he can produce 
the greatest effect." 

— Paley, 1794 

We adhere to the principles of modeless behavior. Larry Tesler defines 
a mode as follows: 

A mode of an interactive computer system is a state 
of the user interface that lasts for a period of time, 
is not associated with any particular object, and 
has no role other than to place an interpretation on 
operator input. 
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Modes are most confusing when you're in the wrong one. Unfortunately, 
this is the most common case. Being in the wrong mode is confusing 
because it makes future actions contingent upon past ones; it changes 
the behavior of familiar objects and commands; and it makes habitual 
actions cause unexpected results. 

We advocate avoidance of modes whenever possible. Of course, 
exceptions must be made, however; there are certain tradeoffs among 
modality, usefulness, and irapleraentability that must be considered. 
There are three cases in which modal behavior is generally tolerated: 

- Long-term modes with a procedural basis: doing word processing 
vs. graphics editing, etc. Each application program in Macintosh 
is a mode. 

- Short-term "spring-loaded" modes, in which the user is constantly 
doing something to perpetuate the mode. Holding down a button or 
key is the most common example of this kind of mode. 

- Alert modes, where the user must rectify an unusual situation 
before proceeding. Such situations, however, should have been 
avoided in the first place. 

Other modes are acceptable if they meet the following requirements: 

- They emulate a familiar real-life model which is itself modal, 
like picking up different-sized paintbrushes in a graphics editor; 
or 

- They change only the attributes of something, and not its 
behavior, like the boldface and underline modes of text entry; or 

- They block most other normal operations of the system to emphasize 
the modality, as in error conditions incurable through software 
("There's no diskette in the disk drive", for example). 

Whatever the modality entails, it must be visible. There must be a 
clear visual indication of the current mode, and the indication should 
be near the object being most affected by the mode. 
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THE GRAPHIC SCREEN 


Macintosh distinguishes itself from all other personal computers by its 
high-resolution graphic screen* While other computers posess similar 
or greater graphics resolution or ability, no other applies its graphic 
powers as widely and generally as Macintosh. 

Macintosh has a purely graphic display: there is no "text mode" in the 
machine at all* Text, to Macintosh, is merely a special kind of 
graphics. Problems of mixing text with graphics go away because 
they're really the same thing. 

Other computers don't do this because of inherent limitations in their 
processor speed and data path width, and because of a lack of software 
support of graphics. Not only does Macintosh have a Motorola MC68000 
microprocessor (running at a nominal 7 MHz with a 16-bit data path, 
giving it several times the bandwidth of the Apple II' s 6502), but it 
also has Bill Atkinson's QUICKDRAW graphics package, revolutionary in 
its speed and ability. 

But far more important than raw graphic power is what the software does 
with it. What Macintosh does can be explained quite simply: 

(hand) 


All commands, features, and parameters of the 
application, and all the user's data, appear as graphic 
objects on the screen. 



Figure 1. Objects on the Screen 

Objects, whenever applicable, resemble the familiar material objects 
they emulate. Objects that act like pushbuttons "light up" when 
pressed; objects that act like tab stops look like their counterparts 
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on a typewriter. Dozens of objects, some emulating everyday objects 
and some unique to Macintosh, are defined in the User Interface Tool 
Box. 

Objects are designed to look beautiful on the screen. Using the 
graphic patterns in QuickDraw can give objects a shape and texture 
beyond simple line graphics. Placing a drop-shadow slightly below and 
to the right of an object can give it a three-dimensional appearance. 
The highest aesthetic sensibilities should be used in the design, 
placement, and animation of objects. 

Graphics can distinguish different states of the same object. Many 
objects on the screen have two states: a "normal" state and a 
"special" state. Most objects in their normal state are predominantly 
white, with detail (lettering, symbols, etc.) in black. Inverting the 
polarity of the object, to make it black with white detail, will 
highlight the object to represent its special state. 


Icons 

A fundamental object in Macintosh software is the icon , a small, 
32-by-32 square graphic that can be drawn, edited, and moved easily. 
The Icon Manager has facilities for drawing icons on the screen and 
setting or resetting bits within them. 



Figure 2. Icons 


Icons should be sprinkled liberally over the screen. Wherever an 
explanation or label is needed, first consider using an icon before 
using text as the label or explanation. Icons not only contribute to 
the understandability and attractiveness of the system, they don't need 
to be translated into foreign languages. 


SCREEN 


Espinosa 10/8/82 









10 


User Interface Guidelines 


Icons are by no means unique to the software; thy appear on the 
Macintosh main unit Itself, on the shipping materials, unpacking 
instructions, and in the user manuals. The standard icons used to 
denote various parts of the Macintosh hardware are shown in the 
Appendix on icons . 
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ACCEPTING USER INPUT 


All meaningful interaction between a Macintosh and its user takes place 
via a piece of hardware built in or connected to the main unit* The 
principal devices for original input to the Macintosh are the mouse and 
the keyboard ; the Macintosh responds to these devices by displaying 
images on the screen or making sounds with its speaker* No other 
action of the Macintosh (such as spinning its disk drive, etc.) 
constitutes a meaningful message to the user* 


The Mouse 

The mouse is a small device the size of a deck of playing cards, 
connected to the computer by a long, flexible cable. There is a square 
button on the top of the mouse. The user holds the mouse and rolls it 
on a flat, smooth surface. 





Figure 3. The Mouse and Pointer 

A pointer on the screen follows the motion of the mouse. Simply moving 
the mouse results only in a corresponding movement of the pointer and 
no other action. Most actions take place when the user positions the 
focus of the pointer (which should be intuitive, like the point of an 
arrow or the center of a crosshairs) over an object on the screen and 
presses the mouse button. 

The purpose of the mouse is to allow high-resolution specification of 
elements on a graphic screen. Many researchers, at Apple and 
elsewhere, have conducted extensive experimentation with various 
pointing devices: cursor keys, light pens, graphic tablets, trac 
balls, etc. We chose the mouse for its ease of use, accuracy, size, 
and cost. It is compact and lightweight; it resolves to 200 points per 
inch; it retains its position when not being used; and it requires 
little muscular strain to position it. 
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Mouse Actions 

The three basic mouse actions are: 

- Clicking : Positioning the pointer with the mouse, and briefly 

pressing and releasing the mouse button without moving the mouse; 

- Pressing : Positioning the pointer with the mouse, and pressing 

and holding the mouse button without moving the mouse; and 

- Dragging : Positioning the pointer with the mouse, pressing and 
holding the mouse button down, moving the mouse to a new position, 
and releasing the button. 

Clicking something with the mouse performs an instantaneous action: 
selecting a location within the user's document or activating an 
object. 

Pressing an object usually has the same effect as clicking it 
repeatedly. For example, clicking a scroll arrow causes a document to 
scroll one line; pressing a scroll arrow causes the document to scroll 
repeatedly until the mouse button is released. 

Dragging can have different effects, depending upon what is under the 
pointer when the button is pressed. Beginning a drag inside the 
document frequently results in selection of data. Beginning a drag 
over an object usually moves that object on the screen. Only certain 
objects are draggable; large draggable objects have a special area with 
which the user drags the entire object. Our tests show that users 
understand dragging an object by a well-marked area rather than by a 
large, general area. 


Pressing 



Clicking 







Figure 4. Clicking, Pressing, and Dragging 

Dragging is also used to choose an item from a menu, as described 
below. 
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(hand) 

In general, pushing the mouse button indicates intention, 

while releasing the button confirms the action. 

Dragging an object attaches a flickering outline of the object to the 
pointer. The outline follows the pointer around the screen while the 
mouse button is being held down. When the user releases the mouse 
button, the object moves to the position of the flickering outline, and 
the outline vanishes. 

Every object is restricted to certain boundaries. If the user tries to 
drag an object out of its natural boundaries, the flickering outline 
disappears when the pointer travels out of those boundaries. If the 
user moves the pointer back inside the boundaries with the button still 
held down, the outline reappears under the pointer and dragging 
resumes. If, however, the user releases the button while the outline 
is invisible, the object being dragged does not move; in this way the 
user can cancel a drag in progress. 


Double-Clicking 

A variant of clicking involves performing a second click shortly after 
the end of an initial click. If the downstroke of the second click 
follows the upstroke of the first by 700 milliseconds or less, the 
second click should be considered not an independent event, but rather 
an extension of the first: this action is called "double— clicking 11 . 
Its most common use is as an optimized means of performing an action 
that can be performed in another, slower, manner. 

(hand) 

To allow the software to distinguish efficiently between 
single clicks and double-clicks on objects that respond 
to both, a function invoked by double-clicking an object 
must be an enhancement, superset, or extension of the 
feature invoked by single-clicking that object. 


Changing Pointer Shapes 

The pointer may change shape to give feedback on the range of 
activities that make sense in a particular area of the screen, in a 
current mode, or both. 

1. The results of any mouse action depend on the item under the 
pointer when the mouse button is pressed. To emphasize the 
differences among mouse actions, the pointer may assume different 
appearances in different areas to indicate the mouse's behavior in 
each area. 

2. Although modal behavior is generally discouraged in the Macintosh 
user interface, sometimes introducing modes makes it simpler to 
differentiate among the multiplicity of functions of the mouse. 

For example, in the Graphics Editor, the mouse functions both to 
draw graphics and to manipulate graphics already drawn. Thus, in 
this particular application, the mouse is employed in two 
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different inodes. To accent the difference in behavior in these 
two modes, the pointer may change shape. 

The facility to change the pointer appearance to convey modal 
information is not a unilateral endorsement of modal behavior; see the 
discussion "About Modes" on page 6 of this document. 


The Keyboard : — ; 

Connected to the Macintosh main unit by a six-foot coil cord is a 
compact alphanumeric keyboard. The keyboard is used mainly for text 
and numeric entry. 

The keys on the keyboard are arranged in familiar typewriter fashion; 
there is a utility program with which the user can change the positions 
of the keys or the characters they generate. 





ALPHA 

LOCK 


BACKSPACE 


RETURN 

SHIFT 


OPTION COMMAND 


ENTER < OPTION 


Figure 5. The Macintosh Keyboard 

In terms of functionality, the keys are divided into three sets: 
character keys, modifier keys, and special keys. Character keys enter 
characters into the computer; modifier keys, in conjunction with 
character keys, choose among different characters on a key; and special 
keys give special instructions to the computer. 


Character Keys 

The alphabetic, numeric, and symbolic keys, and the space bar, enter 
characters into the computer. Any character key may be associated 
(and/or labeled) with more than one character; the modifier keys choose 
among the different characters on each key. 

The Basic Editing Paradigms (see that section) define the ways in which 
characters are typed into a document. All text, whether it be a 
file name, part of a document, or a search pattern, is typed in and can 
be edited in exactly the same way. 
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The keyboard hardware scans the character keys such that it can 
recognize any two character keys being pressed simultaneously. This 
feature is called "two-key rollover”. 


Modifier Keys : SHIFT , CAPS LOCK , OPTION , and COMMAND 
Six keys on the keyboard — two labeled SHIFT, two labeled OPTION, one 
labeled CAPS LOCK, and one labeled COMMAND — change the interpretation 
of keystrokes or other inputs to the computer. When one of these keys 
is held down, the behavior of the other keys (and occasionally that of 
the mouse button) may change. A program can enquire the status of the 
modifier keys at any time. 

The SHIFT and OPTION keys choose among the characters on each character 
key. SHIFT gives the upper character on two-character keys, or the 
uppercase letter on alphabetic keys. OPTION gives an alternate 
character set interpretation, for foreign characters, special symbols, 
etc. SHIFT and OPTION can be used in combination. 

CAPS LOCK latches in the down position when pressed, and releases when 
pressed again. When down it gives the uppercase letter on alphabetic 
keys. The operation of CAPS LOCK on alphabetic keys is parallel to 
that of the SHIFT key, and the CAPS LOCK key has no effect whatsoever 
on any of the other keys. CAPS LOCK and OPTION can be used in 
combination on alphabetic keys. 

The keyboard hardware can sense any or all of the modifier keys being 
pressed simultaneously. 


The COMMAND key 

Pressing a key while holding down the COMMAND key signals that the 
keypress is not data input, but rather a command invocation (see the 
section on Commands). 

(hand) 

As the OPTION and COMMAND keys are unfamiliar features to 
users familiar with typewriters, their use should be 
restricted to expert functions not normally encountered 
by novice users. 


Special keys : ENTER , TAB , RETURN , and BACKSPACE 
When the user enters or edits information, the ENTER key confirms that 
entry. When ENTER is pressed, the computer checks and validates the 
current entry and allows the user to proceed to a different one. 
Commonly used to confirm the entry of text, ENTER tells the computer to 
accept changes made to a field or form (such as a spreadsheet formula 
or a new file name). 

The TAB key is a signal to proceed: it signals movement to the next 
item in a sequence. TAB often carries the implicit meaning of ENTER 
before the motion is performed. 
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The RETURN key is another signal to proceed, but it defines a different 
type of motion than TAB. A press of the RETURN key signals movement to 
the leftmost field one step down (just like a carriage return on a 
typewriter). RETURN also can carry the implicit meaning of ENTER 
before it performs the movement. 

(hand) 

In applications such as the word processor, the TAB and 
RETURN keys not only perform immediate actions, but store 
those actions in the text; in such applications the 
RETURN and TAB keys may be considered character keys. 

BACKSPACE is used to delete characters from text, usually in the course 
of typing that text. The exact use of BACKSPACE is described in the 
section on the Basic Editing Paradigms. 


Typeahead , Auto-Repeat , and Audio Feedback 
If the user types at a time when Macintosh is unable to process the 
keypresses immediately, or the user types more quickly than Macintosh 
can process, the precocious keystrokes are queued for timely 
processing. As keystrokes are handled as events through the Operating 
System's event mechanism, the only limit on the number of characters 
that can be typed ahead of time is the length of the system's event 
queue. 

Normally, Macintosh "clicks 11 slightly at every keystroke. This audio 
feedback in typing is a global preference that the user can change at 
any time (see the Preferences description, in the section on Desk 
Accessories) • 

When the user holds down a key for a certain amount of time, it starts 
repeating automatically. The delays and the rates of repetition are 
global preferences that can be changed by the user at any time. 

All printable characters, the space bar, the BACKSPACE key, and the 
RETURN key, inherently have the auto-repeat ability. The auto-repeat 
ability of each key is a characteristic of the keyboard that the user 
can change with the same utility program that alters the keyboard 
layout. 

Auto-repeat does not function during typeahead; it only operates when 
the application is ready to accept keyboard input. 


Versions of the Keyboard 

There are two physical versions of the keyboard: American and 
European. The European version has one more key than the American. 
The key layout on the European version is designed to conform to the 
ISO standard; the American key layout mimics that of common American 
office typewriters. 

The American keyboard contains 49 character keys (including the space 
bar and RETURN) that produce all the printable ASCII characters. In 
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addition, there are the following modifier and special keys: SHIFT, 
CAPS LOCK, COMMAND , OPTION, ENTER, TAB, and BACKSPACE. 

The European keyboard contains 50 character keys; the special and 
modifier keys are equivalent to those on the American keyboard, but 
their labels denote their functions symbolically. 

(hand) 

As the keyboard interface is a general-purpose clocked 
bidirectional serial port, other devices (such as a music 
keyboard, etc.) may eventually be attached to this port. 


The Numeric Keypad 

An optional numeric keypad is offered that connects between the main 
unit and the standard keyboard. The keypad contains 18 keys that, 
while labeled similarly to keys on the main keyboard, return different 
keycodes to the main unit. An application can thus determine the 
origin of a keystroke. If desired, the keypad keys can be assigned 
ASCII codes equivalent to their counterparts on the main keyboard. 

The character keys on the keypad are labeled with the digits 0 through 
9, a decimal point, the four standard arithmetic operators for plus, 
minus, times, and divide, and a comma. The keypad also contains the 
special keys ENTER and CLEAR; it has no modifier keys. 

The keys on the numeric keypad follow the same rules for typeahead, 
auto-repeat, and audio feedback as the main keyboard. 

Four keys on the numeric keypad are labeled with "f ield-motion" 
symbols: small rectangles with arrows exiting them in various 

directions. Some applications may use these keys to move an object or 
indicator orthogonally around the screen, and require the user to use 
the SHIFT key to obtain the four characters (+ * / ,) normally 
available on those keys. 

(hand) 

As the numeric keypad is optional equipment, no 
application shall require it or any keys available on it 
in order to perform standard functions. Specifically, as 
the CLEAR key is not available on the main keybaord, a 
CLEAR function may be implemented with this key only as 
an optimization of another CLEAR command (such as in a 
menu ) • 
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CONCEPTUAL MODELS 


Macintosh, as an appliance computer, has one purpose only: to 
manipulate information. With it, a user can access, display, 
interpret, modify, transfer, replicate, and destroy information. 
Consequently, the central concepts on which the Macintosh system is 
built deal with things relating to information: 

- The container of information, which we call a file ; 

- The manipulator of information, which we call a tool ; 

- The presenter and interpreter of information, which we call a 
window ; 

- The working environment , which we call the desk top ; and 

- The information itself, which we call a document . 

On the continuum between pure concept and pure object, each of these 
has its own place. We hope to present our users with only the physical 
objects that represent these concepts, so that they can grasp the 
concepts by inference; we will not require them to know the concepts 
before they encounter any of the objects. 

Of the above, files are the most conceptual; we will use the term 
internally here to mean a generic container of information. As 
described below, files have many distinct incarnations that the user 
will encounter. 



Figure 6. Conceptual Models 
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The desk top, documents, and windows are the most concrete of the above 
group: users will see these as objects and not as concepts at all. 

Tools are somewhere in the middle: although they have certain 
distinguishable physical attributes, most of their importance is in the 
conceptual realm. 


Files 

A file is a container of information. All the texts, pictures, charts, 
and address lists that the user puts into Macintosh are stored in 
files. Files also store information that the user didn't create: 
information usually more intelligible to the computer than the user. 

There are three general classifications for files: those containing 
documents , those containing tools , and those containing resources. 
Documents are created by users and can be viewed and modified by users. 
Tools are created by application programmers; the user can use them but 
can t modify them. Resources are also created by application 
programmers, but can be edited by a resource editor to change the way 
in which a tool communicates with the user (see RESOURCE FILES, below). 

Regardless of its contents, a file has many important attributes* 

Every file has a type that describes its contents and determines which 
tools can manipulate it; a size that describes how large its contents 
are; a name by which the user refers to. the file; and a label on which 
the user can put additional information about the file. It also has 
the dates on which it was created and last modified. 


Tools 

What we call a "tool 11 is generally known as an application program: an 
interactive set of procedures and data structures for manipulating 
information. Writing, drawing, charting, filing, analysis, and BASIC 
programming are the fundamental tools Macintosh provides; there are 
also several other housekeeping 11 tools, like using a pocket 
calculator, note pad, and several other "mini-applications 11 described 
later in this document. A tool manifests itself in two ways: it 
displays a menu bar replete with menus of commands appropriate to that 
tool; and it places a document window on the desk through which the 
user can see the information contained in a file. 
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Figure 7. A Typical Tool 

Tools, being themselves information (but intelligible to the computer 
rather than to the user), are stored in files • 

( hand ) 

Only one tool can be in use at any given time. 


Documents 

Documents are the information that the user has created or wishes to 
manipulate. Documents can exist inside a file on a diskette or inside 
the memory of Macintosh. A document comprises a coherent set of 
different kinds of information. 

- Most documents comprise only one kind of information: all text, 
or one picture, or a series of charts, for example. The user 
manipulates the information and prints it out as a whole. Every 
document thus has a principal "type" of information; this type is 
determined by the tool that formed it. 

- A document can comprise more than one kind of information, but it 
must still form a coherent whole. The user qan take information 
of one kind and add it to a document of another kind. But the 
document still retains its principal type, and the user can 
manipulate only the information of that type. 

Associated with each kind of document is a principal tool : the tool 
most appropriate to manipulate that document. The principal tool of 
any document is usually the tool that created it. Other tools may be 
able to read and interpret the document; for example, the BASIC 
language can read word processor documents anticipating the text of a 
program. Such tools are the document's secondary tools. The 
distinction is important only when selecting files from the desk. 


MODELS 


Espinosa 10/ 11/ 82 



CONCEPTUAL MODELS 


21 


Resources 

Some files contain information that is neither a tool nor the user's 
information. This information is usually fonts, system programs, 
configuration information, etc. Although such information may have 
principal tools (such as a font editor for fonts), it's most commonly 
used by a tool. 

Files containing such information are called resource files. Tools 
have internal links to the resource files they need; copying a tool 
file, for example, automatically copies all resource files linked to 
it. Resource files are usually created by application programmers to 
accompany tools. The user can edit some resource files by using 
special resource editors, such as font editors or menu editors. 
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THE DESK TOP MODEL OF ORGANIZATION 

The entire Macintosh working environment is based on familiar and 
intuitive concepts. The Macintosh screen represents a working surface 
or a desk top. Papers, writing or drawing utensils, and other common 
desk accessories have their place on this desk top just as on any 
other. Whenever possible, the objects on the desk top resemble their 
real-life counterparts: for example, all papers are white with black 
lettering. 


Figure 8. The Desk Top 


The Desk 

The desk top metaphor is reinforced by the central tool of the 
Macintosh system, a tool called the Desk . While most tools manipulate 
the documents contained in files, the Desk manipulates the files 
themselves, often regardless of their contents. The basic functions of 
the Desk are as follows: 

- Get, Print, Examine, Delete, or Copy any file or group of files; 

- Initialize a diskette; 

- Rename or rearrange the files on a diskette; 

- Select which diskettes, network diskettes, and peripheral devices 
to work with. 

On the Desk, files are represented by icons, with each file's name as a 
caption to its icon. The icons can be dragged around the desk asnd 
positioned in any order or arrangement. Other parts of the system are 
also represented by icons on the desk: disks and disk drives, 
printers, etc. 
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The central purpose of the Desk is to allow the user to manipulate 
files, and to call up the appropriate tools to work on the documents 
the files contain. The user invokes a tool from the Desk, and returns 
to the Desk when finished. 

Once using a tool, the user can call up a subset of the standard Desk 
functions, to choose a new file to work with or to specify a 
destination for the new work. This subset as presently defined 
includes selecting disks and files, creating a new file, and renaming 
and repositioning files. 
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WINDOWS 


Windows are objects on the desk that display information. The 
information can be a user's document, an error message, or a request 
for more information. Any number of windows can be present on the desk 
at any time. As on a real desk, if more windows are placed on the desk 
than reasonably can fit, the windows "overlap 1 * each other: the windows 
in front partially or completely obscure those behind them. 







I Want You 


The guilty undertaker sighs 
The ionesome organ grinder cries v 
The silver saxophones say I should refuser 
The cracked bells and washed out horns j 
Blow into my face with scorn 
But its not triat way, I wasnt born to lose! 

I want you, I want you, I want you so badj 

The drunken politician leaps 
Upon the street where mothers weep 
And the saviors who are fast asleep, theyf 
And I wait for them to interrupt 
m* rri m .m u . broker 1 . ri m 




Figure 9. Windows 


Each window "floats" in its own plane. Think of a number of plates of 
glass stacked on top of the desk: each plate contains one and only one 
window, and the plates can be moved to make the windows appear in 
different places on the desk. Each window can overlap those behind it, 
and can be overlapped by those in front of it. The frontmost window 
cannot be overlapped. Even when windows do not overlap, they retain 
their front-to-back ordering. 


Opening and Closing Windows 

Windows come up onto the screen in different ways appropriate to the 
purpose of the window. Some windows are created automatically: for 
example, when the user wants to work with a document, the tool being 
used creates a document window in which to present that document. 

Many windows have an icon that, when double-clicked, makes the window 
go away: this icon is called the close box . (This icon is double- 
clicked, rather than singly-clicked, because of the disturbing 
consequences of accidentally clicking the icon). The application in 
control of the window determines what is done with the window when the 
close box is double-clicked: it can 
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1. make the window invisible, to be retrieved later; or 

2. remove and destroy the window and any information it contained. 

If an application wishes not to support closing its window with a close 
boxe, it should not place the box on the window. 






The Active Window 

At any given time, one window is of greater importance to the user than 
any other. Usually, the most important window is presenting the 
current document; at other times, an error message or information 
request may be more important. Thus this general rule: 

- The most important window at any given time is always frontmost. 

Naturally, there must be rules to determine which window is most 
important at any given time. 

- Newly-created windows are usually brought to the front. 

- If the user positions the pointer with the mouse inside any window 
that is not in front, and then clicks the mouse button, that 
window is brought to the front. 

Being in front has more consequences for an window than merely being 
more visible. The frontmost window is said to be active , and all 
others, inactive . 

- A window's active state is visibly distinct from its inactive 
state; usually, the title or header of the window is highlighted. 

- Clicking or dragging inside the active window may perform a useful 
function; clicking or dragging inside an inactive window merely 
brings that window to the front. 

- All command and data input is handled by the program that is in 
control of the active window. 


Document Windows 

Although windows display many kinds of information and requests, the 
most common appearance of a window is to display the document currently 
being worked on. Windows displaying documents have parts not usually 
seen in other windows: scroll bars to move the document under the 
window; a size box to change the size of the window; and split bars to 
divide the window into several panels. 


Scroll Bars 

Scroll bars are used to change the user's view of a document. Only the 
active window has scroll bars; inactive windows leave black-bordered 
empty rectangles where their scroll bars will appear when the window is 
activated. 
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A scroll bar is a light gray shaft, capped on each end with square _ 

boxes labeled with arrows; inside the shaft is a white rectangle. The 

shaft represents one dimension of the entire document; the white 

rectangle (called the thumb ) represents the portion of the document 

currently visible inside the window. As the user moves the document 

under the window, the position of the rectangle in the shaft moves 

correspondingly. 

There are three ways to move the document under the window: by 
sequential scrolling, by "paging" screenful by screenful through the 
document, and by directly positioning the thumb. 

Clicking a scroll arrow moves the document in the direction of the 
scroll arrow. For example, when the user clicks the top scroll arrow, 
the document moves down, bringing the view closer to the top of the 
document. The thumb moves towards the arrow being clicked. 

Each click in a scroll arrow causes movement a distance of one unit in 
the chosen direction, with the unit of distance being appropriate to 
the tool: one line for the word processor, one row or column for the 
spreadsheet, etc. Pressing the scroll arrow causes continuous movement 
in its direction. 

Clicking the mouse anywhere in the gray area of the shaft advances the 
document by screenfuls. The thumb moves toward the place where the 
user clicked, and the document moves in the opposite direction; 
clicking below the thumb, for example, brings the user the next 
screenful towards the bottom of the document. Pressing in the gray 
area keeps screenfuls flipping by until the user releases the button or 
the thumb reaches the pointer. 

In both the above schemes the user moves the document incrementally 
until it is in the proper position under the window; as the document 
moves, the thumb moves accordingly. The user can also move the 
document directly to any position simply by moving the thumb to the 
corresponding position in the shaft. To move the thumb, the user 
presses on the thumb and drags it along the shaft; a flickering outline 
of the thumb follows the pointer. When the mouse button is released, 
the thumb jumps to the position last held by the flickering outline, 
and the document jumps to the position corresponding to the new 
position of the thumb. 

If the user starts dragging the thumb, and then moves the pointer a 
certain distance outside the scroll bar, the thumb detaches itself from 
the pointer and stops following it; if the user releases the mouse 
button, the thumb returns to its original position and the document 
remains unmoved. But if the user still holds the mouse button and 
drags the pointer back into the shaft, the thumb reattaches itself to 
the pointer and can be dragged as usual. 
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Multiple Windows 

Some tools may be able to keep several windows on the desk at the same 
time, as part of the same logical document. Different windows can 
represent : 

- Different parts of the same document, such as the beginning and 
end of a long term paper; 

- Different interpretations of the same document, such as the 
tabular and chart forms of a set of numerical data; 

- Different parts of a logical whole, like the listing, execution, 
and debugging of a BASIC program; 

- Separate documents being viewed and/or edited simultaneously. 
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Figure 10. 


Multiple Windows 


Each tool may deal with the meaning and creation of multiple windows in 
its own way. 

There are occasionally better ways to perform the above functions than 
with multiple windows. Showing different parts of the same document 
can be done better by splitting the window (see below). Different 
interpretations of the same document occasionally merit two panes in 
tVie same window, rather than two separate windows. The implementation 
decision can best be made by experimentation and testing on actual 
users . 


Moving a Window 

Each tool places windows on the screen wherever it wants them. The 
user can move a window — to make more room on the desk or to uncover a 
window it's overlapping — by dragging its title bar. A flickering 
outline of the window follows the pointer until the user releases the 
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mouse button. At the release of the button the full window is drawn in 
its new location. 

A window always moves in its own plane; while it's being dragged 
around, the flickering outline is visible over the windows below it but 
is hidden under the windows above. Notice that clicking in the title 
area does not make a window active or bring it to the top. 

( hand ) 

Moving a window does not affect what portion of the 
document it is displaying. 

A window can never be moved off the screen; specifically, it can t be 
moved such that the visible area of the title bar is less than four 
pixels square. 

Moving a window is fully supported by the Window Manager, and is easily 
performed with one procedure call; an application program need not care 
where on the screen its window is placed. 


Changing the Size of a Window 

If a window has a certain icon in its lower right corner, where the 
scroll bars come together, the user can change the size of the 
window — enlarging or reducing it to the desired size. The box that 
contains the icon is called the size box. 

Dragging the size box drags a flickering outline of the window. The 
outline's top left corner stays fixed, while the bottom right corner 
follows the pointer. When the mouse button is released, the entire 
window is redrawn in the size and form of the flickering outline. 



Figure 11. Moving and Sizing a Window 


Sometimes it's not appropriate to size a window; some tools may not 
support this ability. Iri this case, the size box is empty and clicking 
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in it produces no effect. If a tool does support sizing a window, 
however, changing the window's size leaves the document's size 
unchanged; the window simply displays a larger or smaller portion of 
the document. 

(hand) 

Sizing a window does not affect its contents, or change 
the position of the top left corner of the window over 
the document; only the portion of the view that is 
visible inside the window. 

At its maximum size, a window is still small enough that a seven pixel 
square area of the size box is visible on the screen. 

The minimum size window consists of only a title bar the width of the 
title itself, a horizontal scroll bar (or a blank rectangle of 
equivalent size), and the size box. If a window is made so small that 
its title will no longer fit in the title bar, the title is truncated 
to show as many of its initial characters as possible. 

Sizing a window is fully supported by the Window Manager, and is easily 
performed with one procedure call; an application program need not care 
about the size of a window. 


Splitting a Window 

Sometimes it is desirable to be able to see disjoint parts of a 
document simultaneously. Tools that accommodate such a capability 
allow the window to be split into independently scrollable panels . 

Tools that support split panes place split bars at the top of the 
vertical scroll bar and at the left of the horizontal one, if present. 
Pressing a split bar attaches it to the pointer. Dragging the 
split bar positions it anywhere along the nearby scroll bar; releasing 
the mouse button drops the split bar at its current position, splits 
the window at that location, and creates new scroll bars for each 
panel. 
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Figure 12. Split Views 

The document appears the same, save for the split bar lying across it. 
But there are now separate scroll bars for each pane; whith these, the 
user can scroll each pane independently of the other. 

Dragging a split bar back to its original position reunites the window 
in that direction; the left or top view (and its scroll bar) 
disappears, leaving the right or bottom view. 

The number of views in a document does not alter the number of 
selections per document: i.e., one. The active selection appears 
highlighted in all views that present it. 


Desk Accessories _ 

Macintosh does not allow two tools to be running at once. However, 
there are several mini-applications that are available while using any 
tool. 

At any time the user can issue a command to call up one of several 
desk accessories. The basic ones provided include: 


Calculator 
Alarm Clock 
Note Pad 

Telegram Form and In-Box (AppleGram) 

Accessories are disk-based: only those accessories available on-line 
can be used. The list of accessories is expanded or reduced according 
to what's available at any given time. The application can support all 
accessories in the system with calls to the Desk Manager. On disk, 
accessories are stored in resource files. More than one accessory can 
be on the desk at any given time. 
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Who's on Top ? _____ 

With a virtual three-dimensional screen it is essential to manage the 
third dimension so that important items or objects requiring immediate 
attention are not obscured accidentally. Hence, in order from front to 
back: 

- The pointer 

- An alert, box 

- A dialog box 

- The menu bar and all pull-down menus 

- The active window 

- All other windows 

- The desk top 
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INSIDE DOCUMENTS 




(hand) 

We strongly subscribe to the doctrine of preservation of 
visual fidelity, i.e., what you see is what you get. 

It's important that a document as seen through a window on the desk 
closely resemble the same document when committed to paper. The 
differences (and there will be differences) must be natural and 
unsurprising. Naturally, the ruler and graph paper used to create a 
report on Tuesday morning won't be distributed with that report when 
it's presented that afternoon; printing a document shall not carry the 
vestiges of the tool that created that document. 

Any given tool should be able to manipulate, in some way, everything in 
the document it presents, Macintosh eventually will have many 
different tools, and we do not pretend to foresee the needs of all. 
However, we do provide standard means of manipulating the constituent 
elements of most documents. 


Structure of Documents 

In order to discuss the appearance of information inside documents, it 
is necessary first to digress a bit into the structure of documents. 


A document is a collection of information. Each piece of information 
has its own position in the document, and its own positional 
relationship to the information around it. 

In terms of structure, there are three principal types of documents: 
texts, free-form documents, and structured documents. 

1. Texts consist of a string of information (in this case, 
characters) that appears two-dimensional but is really linearly 
ordered. More characters can be inserted anywhere within the text 
or added onto the end of the text. There is an inherent order to 
the characters in a text, and definite positions between 
characters. 

2. Free-form documents start completely empty and unstructured, like 
a blank piece of paper. Information can be placed anywhere within 
the document; each piece of information has its own position. 

There may be large, empty spaces in the document that contain no 
information. There is no inherent ordering among the information 
in a free-form document. Pictures drawn in the graphics editor 
are free-form documents. 

3. Structured documents have predefined cells to contain information. 
There is a fixed maximum number of cells per document; no cells 
can be added, nor can they be removed. Cells are usually arranged 
in rows and columns; a given cell is a member of one row and one 
column. There is a definite position between two adjacent cells, 
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and a position at the corner of a group of four cells. A 
spreadsheet is a structured document. 


(KHKHXHXHXHKHJOtHJOOOOU^ 

r 1 " Text 

^KKXHJOooaaauQQQQoaaQ 



Figure 13. Types of Documents 

The type of a document affects many things — mostly how a user selects 
information inside the document. For example, information in a text 
can be selected character-by-character, but information in a structured 
document is selected cell by cell. The exact details of the selection 
process are described in the section "Selecting Information". 


The Visual Structure 

The structure can manifest itself visibly inside the document. For 
example, the rows-and-columns arrangement of a spreadsheet can be 
clarified by adding graphic grid lines between the cells. These lines 
are not part of the user's data, but they are part of the document. 
Such supporting graphics are usually static elements within the 
document, and cannot be moved or altered. Those that can be altered 
usually affect only the presentation of the user's data, not the data 
itself. 

At the tool's discretion, the supporting graphics in a document may or 
may not appear when the document is printed. The grid lines on a 
spreadsheet might very well appear, while the rulers in a word 
processor document will probably not be printed. 


Graphics in Documents 

Not only does Macintosh use graphics to show the structure of a 
document and to otherwise communicate with its user, it also supports 
tools to create and manipulate graphic documents. Two such tools are 
planned: a graphics editor (to design and draw pictures, diagrams, 
illustrations, signs, etc.), and a charts and graphs package (to do bar 
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charts, pie charts, hi-lo graphs, etc. from a numerical data base). 

Graphic documents are usually free— form: each graphic item in the 
document has its own position within the document, and there is no 
inherent relationship among the items (although the tool can define 
such a relationship). But there / s no reason that graphic documents 
can't be structured. For example, a graphic programming language raught 
have a text-like or other structure. 



Figure 14. Graphic Documents 

Graphics inside documents are produced using the QuickDraw graphics 
package. The package can draw seven fundamental graphic forms — lines, 
rectangles, ovals, rounded-corner rectangles, wedges, polygons, and 
arbitrary regions — either in outline or filled with a solid pattern. 

It can also place and manipulate images defined bit— by— bit. A tool can 
give the user the ability to draw anything from simple line drawings to 
finely textured halftone pictures. 

The tool must itself determine how to respond to the mouse and keyboard 
in creating and manipulating graphics. 


Appearance of Text _ 

Most people, even bibliophobes , are confronted with a wide variety of 
printed matter on daily basis. Our eyes are so accustomed to seeing a 
myriad of typestyles, typesizes and typefaces used in publications to 
embellish or emphasize the content, that we no longer take special 
note. Developing eye-catching and pleasing typefaces has been an art 
unto itself since Gutenberg. Appropriate and aesthetically embued 
typesetting has been traditionally the domain of tooled craftsmen. ,By 
contrast, the repertoire of currently available computer typefaces is 
thoroughly devoid of aesthetic nuances and provides but a bleak parody 
of the printed world. 
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Macintosh documents can contain characters in a number of different 
typefaces, types tyles, and typesizes. Type can abut closely or appear 
loosely packed; parts of some characters (such as the curl of a y) can 
reach back under or up over adjacent characters; and text can freely 
intermix with graphics. After all, text is just a specialized form of 
graphics. 

Note that in this context, numbers are considered text: to users, the 
external appearance of digits is the same as that of other text 
characters. The following discussion thus pertains to numerical 
information as well as natural-language text. 

- For more information on the aesthetics of type design, see a good 
typography book; David Gates' Type is recommended. For 
implementation details on how to place characters on the screen, 
see the Macintosh User Interface ToolBox manual 
QuickDraw: A Programmer's Guide . 


Typefaces , Typesize , and Fonts 

A typeface is a set of typographical characters composed with a 
coherent "feel" and consistent design. Things that relate characters 
in a typeface include the thickness of vertical and horizontal lines, 
the degree and position of curves and swirls, the use of serifs, etc. 
Typefaces have names, usually historical: Bodoni, Goudy, Tile, etc. 

The identity of a typeface is independent of its size or any particular 
typestyle it may conform to (see below). 

Typesize in the printing world is measured in points, a point being 
reasonably close to 1/72 inch. The resolution (in points per inch) of 
the Macintosh screen is quite close to this, but not close enough to 
keep accurately to printers' measurements. But we do describe typesize 
loosely in "points 11 , which have no correlation to the mathematical 
entity of a point in the QuickDraw graphics package, or to anything 
else for that matter. In talking about type, we use points as a rough 
indication of vertical size. 

A font is the entire set of characters of a specific typeface and 
typesize. For example, Helvetica8 refers to a font that contains 
characters of the typeface named Helvetica at a size of 8 points. In 
addition to all the uppercase and lowercase letters, numerals and 
punctuation marks, a font may include mathematical symbols, accented 
letters or other special characters. 
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Figure 15. Type 


Typestyles 

Macintosh does not require the use of separate fonts to accommodate 
different styles of the same typeface. A character of any font may be 
subjected to a group of transformations that modify its general 
appearance: such a modification is called a types tyle . There are five 

fundamental typestyles: bold characters, italic (slanted) characters, 
outlined characters, underlined characters, and shadowed characters. 

Any combination of these typestyles can be used, but Macintosh cannot 
be held accountable for any aesthetic atrocities that may be 
perpetrated by an insensitive user. 


Proportionally Spaced vs . Monospace Fonts 
Most printing fonts are proportionally spaced (also known as variable 
pitch). This means that, for example, the "i" is narrower than an V 1 ; 
the "W" wider than the 11 J". 

In a monospace (fixed pitch) font, all characters are of the same 
width. Monospace fonts are generally less attractive than 
proportionally spaced fonts. Monospace fonts are sometimes called 
"typewriter" fonts. 

Monospace fonts are appropriate for some applications, such as COBOL 
coding forms, but generally discouraged in Macintosh. As monospaced 
fonts are merely a degenerate case of proportional fonts, they can be 
used just as easily as proportional fonts, when they are needed. It's 
necessary, for example, for proportional fonts to have monospaced 
numerals, so that columns of numbers line up neatly when aligned at 
decimal tab stops. 
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Standard Fonts 

Macintosh uses a distinct system font when presenting its labels, 
messages, and lists to the user. System-provided text in this font 
cannot be edited. The Macintosh system font is CreamlO; users and 
tools may not use this font. 

There is always a standard font in which all information the user has 
entered will appear: the user font is HelveticalO, a nice, sans serif, 
reasonably compact face. 

The use of any other fonts depends on the particular tool being used. 
The word processor, in all probability, will allow the user more 
multiple font ability than most other tools. 
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WORKING WITH MACINTOSH 


So far, this document has described many things about the Macintosh 
user interface: how it accepts inpout from the user, how it displays 
information on its screen, and how the conceptual underpinnings of the 
system control the structure of interactions* But nothing has been 
said about how these things work together* 

This section describes how input affects output: how Macintosh works. 
It discusses the methods the user will use to perform actions, select 
information, and choose commands to operate on that information* 


Direct Manipulation : Controls — 

"Piaget has hypothesized that infants first learn about 
causation by realizing that they can directly manipulate objects 
around them— pull off their blankets, throw their bottles, drop 
toys.** Such direct manipulations, even on the part of infants, 
involve certain shared features that characterize the notion of 
direct causation that is so integral a part of our constant 
everyday functioning in our environment— —as when we flip light 
switches, button our shirts, open doors, etc*" 

— Lakoff & Johnson, 1980 

Friendly systems act on direct causation—— they do what they re told* 
Performing actions on a system in an indirect fashion (by typing words 
and pressing RETURN, or by obediently choosing one item from the 
currently displayed list) reduces the sense of direct manipulation that 
is basic to the feeling of causation* To give Macintosh users the^ 
feeling that they are in control of their machines, many of a tool s 
features are implemented with controls : graphic objects that, when 
directly manipulated by the mouse, cause instant action with graphic 
results* 

Three kinds of controls are supported by the Control Manager in the 
User Interface ToolBox: buttons, check-boxes, and dials* 


Buttons 

Buttons are small objects, usually inside a window (but occasionally on 
the desk top), labeled with words or an icon. Clicking or pressing a 
button performs the instantaneous or continuous action described by the 
button's label* 


Buttons usually perform instantaneous actions, like opening or closing 
windows, or acknowledging error messages* Occasionally, they can also 
perform continuous action: the scroll arrows on a scroll bar are 
continuous-action buttons. 
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The Control Manager defines one kind of button, an instantaneous or 
continuous pushbutton, labeled with a verbal title. A tool may include 
a procedure to define a custom button, which can be linked in to the 
Control Manager and used just like the standard button. 


Check-Boxes 

Check-boxes are a variant of buttons. Where buttons perform 
instantaneous or continuous actions, check-boxes display a state that 
the user can change. Most commonly seen when filling out a form or 
setting parameters, check-boxes are small squares that appear either 
empty or filled in with a check-mark. The boxes are usually adjacent 
to a word or icon that describes the meaning of the box. 

Clicking in a check-box flips its state, from checked to unchecked or 
vice-versa. Dragging through a field of check-boxes flips the state of 
the first and assigns the new state to all other boxes dragged through. 

A check-box may belong to a group of boxes. If there are no 
interrelationships among the boxes, they are checked and unchecked as 
above. But if the boxes are related such that one and only one must be 
checked at any given time, they work like "radio buttons": clicking in 
an unmarked box marks that box and unmarks the previously marked box. 
Such groups should be labeled clearly, "Choose one of the following:". 
The checked appearance of this kind of box is visually distinct from 
normal, ungrouped check-boxes. 


(Button 1) 
( fatten 2 ) 

D ChecJc-Bcuc 1 
□ Chedr-Box 2 




Figure 16. Buttons, Check-Boxes, and Dials 
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Dials 

Dials display the value, magnitude, or position of something in the 
tool or system, and optionally allow the user to alter that value* 

Dials are predominantly analog devices, displaying their values 
graphically and allowing the user to change the value by dragging an 
indicator; dials may also have a digital display* 

The best example of a dial is the shaft of a scroll bar* The indicator 
of the scroll bar is the thumb; it represents the position of the 
window over the length of the document* The user can drag the thumb to 
change that position* 


Just as with buttons, there are a few standard dials defined in the 
ROM, but a programmer can implement a custom dial and link it in with 
the control mechanism* 

Selecting Information — 

A previous section mentioned that Macintosh has one purpose only. to 
manipulate information. If this is true, then there is a simple 
operational paradigm to cover all situations: 

(hand) 

First select some information, then manipulate it* 

This paradigm minimizes modality in basic operations* By selecting the 
information first, the user is free to select different information 
without being committed to a certain manipulation. 

The following sections describe the two parts of this basic paradigm, 
how to select information in a document, and how to choose commands to 
manipulate that information* 


The Selection 

The selection is the collection of information that will be acted upon 
by the next command* There is always one and only one active selection 
in the active window* The selection can be so large as to enclose all 
the information in the document, or it can be so small as to merely 
indicate the position between two pieces of information, enclosing 
nothing at all; the latter selection is called an insertion point . The 
insertion point indicates the position at which newly entered 
information will be placed* 

Positioning the pointer over the user's information in the active 
document and pressing the mouse button usually begins a selection* 

Once the button is pressed, the selection can be completed in two ways: 

1 • Clicking selects one piece of information or a position between 
pieces of information* 

2* Dragging selects a group of information. 
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This is I 


text in a text document. 
Notice that chexe.cters ere inserted in 
3tep with the moving 


afointer, 



Figure 17. Selecting Information 

The exact behavior of clicking and dragging to make the selection 
depends on the structure of the document. 

— Clicking in text selects the position between the two characters 
nearest the pointer; this position becomes the insertion point. 
The insertion point in text is represented by a blinking vertical 
bar. 


Clicking in a structured document selects either the cell under 
the pointer, the position between two adjacent cells, or the 
corner of four cells. The latter two selections are insertion 
points, and are represented by blinking vertical or horizontal 
bars, or by a blinking cross. 

Clicking in a free-form document selects the item under the 
pointer. If the pointer is not over a piece of the user's 
information, clicking either does nothing, or selects a position 
in the document. This position, the insertion point, is marked by 
an "anchor" icon. 
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This is text in & text, document. 
Notice that characters are inverted in 
step with the j moving pointer. ][ 



Figure 18. Selection by Clicking 

Clicking in editable user information always creates a new selection; 
the information selected is highlighted and the previous selection is 
unhighlighted. Highlighted text appears white-on-black; highlighted 
graphics appear with "knobs". 

Dragging through editable user information selects a group of 
information. It would seem that dragging should select all items 
dragged over — to select items, press the mouse button, drag across the 
items, then release — but experience proves that selecting only those 
items that were dragged over is inefficient. Instead, consider 
dragging as defining two points: the point where the button was 
pressed and the point where it was released. Dragging then selects 
everything between those two points, according to the structure of the 
document, regardless of the path of the mouse. The objects under the 
two points are included in the selection, as are all items between 
those two points. 

- Dragging through text selects all characters, in textual order, 
from the character under the first point to the character under 
the last point. 

Dragging through a structured document selects all cells in the 
rectangle whose corners are the cell under the first point and the . 
cell under the last point. 

Dragging through a free-form document selects all items completely 
enclosed by the rectangle whose corners are the first and last 
points. 

During the dragging, the selection is visible — the items that will be 
selected are highlighted, in real time, according to the current 
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position of the pointer. But the selection is not actually confirmed 
until the mouse button is released. If the user moves the pointer back 
to the first point and releases the mouse button, the result is the 
same as a click at that position (see above) 

The items between the two points are selected regardless of the 
relative orientation of the two points. Starting at the end of a 
sentence and dragging backwards to the beginning operates just as well 
as starting at the beginning and dragging to the end. 

Once the selection is made, the selected items are highlighted and the 
items in the previous selection are unhighlighted. There is no 
mechanism for restoring the previous selection, 

(hand) 

After a selection is made, the pointer becomes invisible 
so as not to obscure the selection. The pointer 
reappears the next time the user moves the mouse. 


Selection by Command 

Some logical groupings of information are more commonly selected than 
others — columns or rows in a spreadsheet, paragraphs in a word 
processor, etc. And occasionally it's convenient for the tool to 
select a piece of information automatically — such as a word or phrase 
that the user is searching for. 

In these cases, the invocation of a command may explicitly or 
implicitly make a new selection. For example, a tool may have a 
"Select All" command to select all information in the document; a 
spelling checker could have a "Select Next Misspelled Word" command, 
etc. 

When any such command is invoked, the tool must scroll the document 
automatically in order to present as much as possible of the new 
selection. 


Automatic Scrolling During Selection 
The only limit on the size of the selection is the size of the document 
itself; the largest possible selection is the entire document. 

But the normal method of selecting as outlined above can't handle 
selections that extend outside the window. We therefore define a way 
to scroll the contents of the window during selection: 

- If during selection the user drags beyond the borders of the 

window, the contents of the window will scroll (automatically and 
continuously) away from that border. New information scrolled 
into the window becomes selected and is highlighted accordingly. 
Scrolling stops when the user either releases the mouse button or 
moves the pointer back into the window: the latter case resumes 
normal selection. 
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“Window" in the above paragraph applies to a single panel of a split 
window; beginning a selection in a panel and moving out of that panel 
scrolls only that panel. 


Extending the Selection 

Selection by dragging and automatic scrolling is fine for relatively 
small selections, but its usefulness deteriorates as the desired 
selection grows larger* An alternate method can be used to make a 
large selection: this process is called extending the selection * A 
selection made in this way is treated the same as any other selection* 

Extending the selection merely adds to the current selection. Whereas 
making a normal selection removes the previous selection, making an 
extended selection enlarges the previous selection to extend to the 
newly selected position. 



Figure 19. Extending a Selection 

An extended selection is made by positioning the pointer, holding down 
either of the SHIFT keys on the keyboard, then pressing the mouse 
button. When the mouse button is pressed, all information between the 
original selection and the current pointer position (inclusive) becomes 
selected and highlighted. The user can then drag the mouse around and 
complete the selection as usual. The SHIFT key may be released at any 
time without affecting the selection. 

Extended selections can be made across two panels of a split window. 
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Making a Discontiguous Selection 

Some tools may choose to allow selections that are discontiguous: that 
comprise one or more unconnected pieces, that have "holes", or both. 

How a tool deals with operations on such selections is up to its 
designers; the following is merely an outline of how such selections 
are made. 

(hand) 

Discontiguous selection of text is not supported. It 
causes ambiguity upon insertion. 

Making a discontiguous selection is like making an extended selection 
in that it merely augments the current selection, and also that it is 
invoked by holding down a keyboard key while pressing the mouse button. 



Figure 20. Making a Discontiguous Selection 

A discontiguous selection is made by positioning the pointer, holding 
down the COMMAND key, and pressing the mouse button. It continues like 
a normal selection: the user drags the mouse to indicate the last 
point, then releases the mouse button. The COMMAND key may be released 
at any time without affecting the selection. But the kind of selection 
that's being made depends upon the posiition of the pointer when the 
mouse button is pressed: 

- If the pointer is not inside the previous selection, the operation 
is a normal selection that does not remove the previous selection. 
Both selected areas are highlighted on the screen; they are both 
considered parts of the selection. 

- If the pointer is inside the previous selection, the operation 
becomes a deselection: the information "selected" becomes 
deselected and unhighlighted. The remaining information, even if 
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it contains a hole, is the selection. 

With this paradigm, any arbitrary collection of items in the document 
may be selected. Once again, the selection comprises all highlighted 
items; there is one and only one selection. 

Discontiguous selections can be made in any pane of a split window. 
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Once the information to be operated on has been selected , a command to 
operate on that information can be chosen from lists of commands called 
menus • 


A principal problem with menu-driven systems is that it's difficult for 
the menu to share the screen with the information being worked on, and 
especially difficult to show all menus at the same time. Most systems 
"solve 11 these problems with modal tree-structured hierarchies of menus, 
where menus are chosen from a menu of menus, while the user's 
information has disappeared from the screen. Unfriendly because it 
segregates information from commands, and confusing because it forces 
users to "walk" up and down trees of menus, this approach will not work 
for Macintosh. Instead, taking advantage of Macintosh's ability to 
overlap things on the screen, we make all menus available at all times 
(with the user's information still visible) by means of pull-down 
menus • 


The Menu Bar 

The menu bar is displayed at the top of the screen. It contains a 
number of words and phrases: these are the titles of the menus (see 
below) associated with the current tool. The contents of the menu bar 
and the corresponding menus are different for each tool. In this sense 
the tool is said to "own" the menu bar. 

There is one and only one menu bar on the screen at any time. 

Exceptions may be made in special cases: full-screen games may need no 
menu bar, for example. 

(hand) 

The titles in the menu bar, and their corresponding 
menus, should remain constant throughout the tool. A 
tool should not change the available menus or put up 
different menu bars at different times. 


Of Mice and Menus 

The user positions the pointer over a menu title on the menu bar and 
presses and holds the mouse button. The title becomes highlighted and 
a rectangular menu descends from the menu bar under the title; it 
remains down as long as the mouse button is held down, or until the 
user moves the pointer away from the menu. 

The menu contains a number of items, usually stacked vertically inside 
the menu; each item names an operation that can be performed. The 
items may contain words, icons, or both. To invoke a command in the 
menu, the user drags the pointer down to the menu item (which becomes 
highlighted) , then releases the mouse button. As soon as the 
mouse button is released, the menu item blinks briefly, the menu 
disappears, and the command is executed. The menu title in the 
menu bar remains highlighted until the command has completed execution. 
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Menu Bar 


Menu Item 
Menu Item 
Menu Item 


Menu Item 


Menu 


Figure 21. Pull-Down Menus 

Because the user chooses a menu item only by pointing the pointer at 
it, and its command takes effect only when the mouse button is 
released, if the user drags the mouse outside the menu area (when e 
menus are showing) and releases the mouse button, no command is 
selected and no action takes place. Thus there is always recourse 
should the user have a change of heart after pulling down a menu, and 
the user is never forced to activate a command. 

(hand) . . 

The menu items, and NOT the menu titles in the menu ba , 

act upon selections. Users should always be able to 
peruse the inventory of commands by dragging the pointer 
across the menu bar without fear of causing something to 
happen. 

The only way to pull down a menu is to press the mouse button while the 
pointer is in the menu bar. While the user is holding down the 
mouse button, the pointer does nothing but pull menus down and 
highlight their items. 

If the user tries to perform an operation on a selection that is not 
currently visible, automatic scrolling occurs to make the selection 
visible before the operation is performed. The document scrolls until 
the selection is completely in view or, if the selection is very large, 
the entire window is filled with the part of the selection nearest o 
the current position; then the chosen operation is performed. 


Notes on General Properties of Menus . — - — 

Not all menu items are relevant at all times. A menu item that s 
inapplicable to the current selection is visually distinct from e 
others (perhaps grayed out) and will not highlight when a user ^ e ® ° 
choose it. Repeated attempts by the user to choose an ineffective 
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item warrant explanations from the alert mechanism (see SPECIAL 
CONDITIONS) . 

(hand) 

A menu in the menu bar can always be pulled down, even if 
all its menu items are ineffective; in such cases, the 
menu title is also grayed out* The user should always be 
able to survey all the available commands, even if they 
are inoperative* 

Commands that may be invoked from the keyboard with the COMMAND key 
(see below) have a special notation on the right side of the menu* The 
notation consists at present of an apple symbol and the key that is 
used with COMMAND to invoke that command* 

Menu items are grouped in a menu to emphasize the logical relationships 
among the groups* Groups are separated by a one-item-high blank space 
that serves to visually distinguish the groups. This space is not an 
item and is not highlighted when the pointer moves over it. 

Experience shows us that it's easiest for users to choose the second, 
third, and fourth items in the menu: thy 7 re far enough away from the 
menu bar to reach them without overshooting, but still not too much of 
a reach down* We recommend that the most common and safest commands go 
in these positions* 

Also in regards to safety, the commands that cause the greatest effect 
(such as Quit) should be separated from other, less "dangerous 11 
commands* Similarly, pairs of commands that perform similar functions 
with slight differences should not be adjacent; a user may choose one 
accidentally, intending the other, and not notice the subtle 
difference* 


( Title Title Title 1 


Title Title Title ^ 

1 

1 

1 

1 

j 

Item 

Checked Item 

Apple-key A 
Item 

/teas 

Item 



Figure 22* General Properties of Menus 
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Some commands come in pairs, with only one command of the pair being 
appropriate at any given time. Most often these pairs control the 
appearance of something on the desk: one command makes the object 
visible, and the other command makes it invisible. For example, in the 
Word Processor, the rulers that set margins and paragraph formatting 
are normally visible in the window. If the user wishes to remove the 
rulers, there is a command called "Hide Rulers". When the user invokes 
this command, the rulers disappear and remain hidden; meanwhile, that 
command has been replaced with its counterpart, "Show Rulers". 

(hand) 

These are not two different commands; they are opposite 
sides of the same command. The intent of this pairing 
method is to shorten and simplify menus. The pairing 
does not make a good indicator of state. 

Some status information can be conveniently shown in menus, with the 
commands that affect that status. If all the information in the 
selection shares a certain characteristic, and that characteristic can 
be set with a menu command, that command is marked with a check-mark to 
show the state of the selection. 

Also, in situations where commands in a menu not only perform their 
function on the selection, but also set a state that controls the 
interpretation of subsequent input (such as the Bold command), the 
commands whose states are currently in effect are similarly marked. In 
this way the menu allows the user not only to change how subsequent 
input will be interpreted, but also to see the interpretation before 
changing it. 


The Standard Menus __ 

Although the titles on the menu bar are different in each tool, the 
three menus at the left of the menu bar (the Apple, Edit, and File) 
remain the same at all times. 

The commands and information in these menus pertain to functions common 
to all Macintosh users: inquiring the state of the current tool and 
data, invoking global system functions, and loading, saving, and 
printing documents. 


The Apple Menu 

Apple 

Calculator 
Alarm Clock 
Note Pad 
AppleGram 


Tool Information 
Document Information 
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Beginning the Apple menu are the names of the desk accessories 
currently available to the system. Choosing a name activates the 
corresponding accessory and places it on the desk; double-clicking the 
close box on the accessory makes it disappear and reactivates the 
previously active window. The list of available accessories changes 
with the availability of the accessories themselves. 

The "Tool Inf ormation" and "Document Information" commands in the Apple 
menu let the user see information pertaining to the current state of 
the tool being used (its author, publisher, copyright message, version 
number, perhaps a hotline number) and the current document (its size, 
file name, label, creation and modification dates, "home" location or 
diskette, and any other status information). 

These commands, when invoked, present a window that contains the 
appropriate information; the window remains on the desk top until the 
user explicitly removes it by double-clicking its close box. 

The document information window gives the user the ability to see 
important but little-used information about the current document, 
without taking up valuable screen space when the information isn't 
needed. The tool information is an important tool in the continued 
support of the customers should anything go wrong with a tool, the 
users have a way to refer to the exact version number of the 
problematic program when seeking help from a dealer or hotline. 

In tools that have a global "help" facility, the Help command appears 
at the bottom of the Apple menu. 


The Edit Menu 

The Edit menu includes all the editing commands necessary to manipulate 
pieces of documents. 

Edit 

Undo {what} 


Copy 

Cut 

Paste 


Select Everything 

The effects of the four editing commands are more thoroughly discussed 
in the BASIC EDITING PARADIGMS, below. Briefly, Cut removes the 
selection from the document, storing it in an intermediate window 
called the scrap; Paste replaces the current selection with the 
contents of the scrap; Copy duplicates the selection into the scrap 
without removing it from the document; and Undo negates the action of 
the immediately previous command. 

Selection commands and other editing functions appropriate to the 
current tool may also appear in the Edit menu, but the location and 
order of the first four items must not change. 
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The File Menu 

Although the exact functionality and layout of the File menu has yet to 
be worked out, our current thinking has it resembling this: 

File 

Quit this tool 


Save this document 
Print this document 


Get another document 

" Save this document 11 saves the current document into a file; Get 
another document 11 gets a new document from another file; and Print 
this document 11 invokes the printing subsystem of the tool. 

"Save" and "Get" allow the user to use a limited subset of the Desk 
functions in selecting, creating, or naming the file associated with 

the document. 

The "Quit" command is in the Files menu to make sure that users see 
their opportunity to save their work before quitting. Conversely, in 
the process of saving their work, they see their opportunity to leave 
the tool. If the user chooses to Quit before saving the document, the 
tool should give a gentle yet firm reminder that quitting now will 
cause the loss of all that information, and request confirmation before 
actually qui 1 1 ing • 


Keyboard- Invoked Commands 

The editing paradigms described below allow a user to perform all basic 
object manipulation-adding, removing, replacing, and moving using the 
keyboard to enter text, the mouse to select text, and the commands in 
the Edit menu to manipulate it. 

But this paradigm is likely to generate a lot of hand-waving the 
user's hand must move from the keyboard to the mouse, and move the 
mouse from the document to the menu bar. As an optimization to reduce 
hand motion, common commands available on the three standard menus may 
also be invoked from the keyboard, by using the COMMAND key in 
combination with another key. 

(hand) 

When the user holds down the COMMAND key on the keyboard 
and presses another key, that key is interpreted not as 
text entry, but as an invocation of a menu command. If 
the key does not correspond to any implemented command, 
the alert mechanism is invoked to beep at the first 
occurrence and give an alert message at any subsequent 
occurrences • 

When one of these command keys is pressed, the menu title of the menu 
containing the corresponding command highlights while the operation is 
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being performed, then reverts to normal. The menu itself does not pull 
down. 

The currently defined command keys are as follows: 


COMMAND 

z 

Paste 

COMMAND 

X 

Cut 

COMMAND 

c 

Copy 

COMMAND 

V 

Undo 

COMMAND 

space 

Save this document and quit 

COMMAND 

/ or ? 

Help 


In all tools that have a Format or Types tyle menu to change the 
types tyle while entering text, the following command key aliases are 
supported: 


COMMAND 

Q 

Plain text 

COMMAND 

w 

Boldface 

COMMAND 

E 

Italic style 

COMMAND 

R 

Outline style 

COMMAND 

T 

Underlined 

COMMAND 

Y 

Shadowed 


The commands, just like their counterparts in the menus, are 
cumulative: pressing COMMAND E while Boldface is already in effect 

results in bold italic text. The Plain Text command undoes all other 
styles. 

The "OK" and "Cancel" buttons in dialog boxes (see below) also have 
command aliases: 

COMMAND Enter OK 

COMMAND ' or Cancel 

Several emergency commands can be invoked from the keyboard. Note that 
rebooting the system is not among them. 

COMMAND • Stop current operation 

COMMAND 1 Eject internal diskette 

COMMAND 2 Eject external diskette 
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(hand) 

The command keys are aranged positionally, not 
mnemonically . The command keys retain their position 
(not their alphabetical characters) on foreign keyboards. 


What Commands Are and Aren't — 

— Commands, when invoked, operate immediately and return control to 
the user when completed. 

— Commands operate on something visible in the active window, or add 
or remove a window on the desk. 

— Commands that manipulate user information always operate upon the 
active selection, never upon any nonselected data. 

— Commands are either verbs or verb phrases, never nouns with an 
implied verb. 

— Most importantly, commands don't put the tool into an invisible 
modal state. 
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The Macintosh User Interface ToolBox contains a set of core editing 
routines that standardize the ways the user edits and manipulates text. 
As long as application programmers use this package properly, every 
piece of editable text the user sees on the Macintosh screen can be 
edited using the same quick, consistent methods. The paradigm below 
supports: 

- Inserting, deleting, and replacing text; 

- Moving text from one place to another in the same document; 

- Carrying information between two similar or dissimilar documents. 

The core editing routines also handle font changes, typestyles, and 
paragraph formatting; these abilities are further discussed in the 
documentation of those routines. 

(hand) 

The following discusses only the operation of Cut, Paste, 

Copy, Undo, insertion, and replacement on text . The same 
procedures should operate in a conceptually parallel 
manner on non-text items, i.e., graphics, spreadsheet 
cells, etc. It is the responsibility of the designers 
and programmers to maintain consistency in the editing 
operations on non- text items. 


The Selection 

As described in the section on "Inside Documents", there is always one 
and only one active selection in an active window that contains 
editable text. A selection takes one of two forms: 

1. A selection between two characters that encloses no text: this 
appears as a blinking vertical bar and is called an insertion 
point. 

2. A selection enclosing one or more characters of text. 

The editing commands Cut, Paste, Copy, and Undo, whether invoked from 
the Edit menu or by the COMMAND key on the keyboard, act upon the 
selection. Typed characters also affect the selection. 


The Scrap 

The scrap goes hand in hand with the Edit menu. It is a very special 
kind of window with a well-defined function: it holds whatever is cut 
or copied from a document. It sticks around, its contents intact, when 
the user changes tools. 

Every time the user performs a Cut or Copy on the current selection, a 
copy of the text in the selection replaces the previous contents of the 
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scrap. 


The user can't select the scrap or any information inside it. But the 
scrap window can be dragged around by its title bar, and can be 
enlarged or reduced by dragging its size box. In most ways the scrap 
behaves just like any other window. 


I'm urnra pave- 
ment, thinkiri 


Subterranian 


■anian Hcrnj 


Col 


J'm pavement, 
thinki/y 


n Sc 


on the 




J bout the govern- 
ment. Man! 


ini the 


Q' : . . Scrap 


on the 


Paste 


on the 


Scrap • 


J bout the govern- 
ment Man niiiiit 


trenchcoat, badge 
out, lEffifSIfl says 


on the 


Copy 


trenchcoat, badge 
out, IHBBil says 


5":'' Scrap 


laid oil, 


Figure 23. Use of the Scrap 


There is only one scrap, which is on the desk for all tools that 
support Cut and Paste (it's hidden during games and such). If the user 
doesn't want the scrap to interfere with other things on the screen, 
the scrap can be shrunk to its smallest size, dragged nearly off the 
screen, or buried under other documents. Nothing changes the contents 
of the scrap except Cut, Copy, and Undo. 


As the contents of the scrap remain unchanged when applications begin 
and terminate, the scrap can be used for transferring data among 
mutually compatible applications (see "Cutting and Pasting between 
Tools" , below) . 


The Cut and Copy commands 

The Cut command removes the current selection from the active document 
and puts it in the scrap. The selection completely replaces the 
previous contents of the scrap. The selection in the document is 
reduced to an insertion point. 

If a Cut is attempted when the selection is an insertion point, Cut 
doesn't light up in the menu when chosen. This prevents people from 
accidentally cutting twice and losing the scrap. 

Perfoming a Copy command puts a copy of the current selection into the 
scrap, without changing the original selection in the active document. 
Just as with a Cut, every Copy completely replaces the previous 
contents of the scrap. Also like Cut, the Copy item won't light up if 
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the selection is an insertion point. 


Paste r 

The Paste command is the effective antonym of Cut: it replaces the 
current selection with the contents of the scrap# A Paste leaves the 
contents of the scrap unaltered; the selection is set to an insertion 
point at the end of the pasted text. With this, successive invocations 
of Paste replicate the contents of the scrap at the selected position 
in the document. 

(eye) 

Notice that in a Paste over an existing selection, the 
contents of the selection do not go into the scrap; they 
can be recovered only by an immediate invocation of Undo. 


Undo . 

Finally, the Undo command is a one-level negation of the last command. 
It always applies to all Edit commands; additionally, any larger scope 
of Undo can be added by the application. If the previous operation was 
an Undo, it undoes that Undo. 


Inserting and Replacing Text 

New text can be entered from the keyboard or numeric keypad. Typing 
new text operates much like a Paste command. 

Typed text replaces the current selection . If the current selection is 
an insertion point, the typed characters appear at the insertion point 
and the insertion point moves past the characters. If the current 
selection includes text, the entire selection is automatically reduced 
to an insertion point, deleting the text; insertion then proceeds as 
described above. 

(hand) 

Notice that if a selection is replaced with an entry from 
the keyboard, the selection does not go into scrap. Its 
contents can be recovered only through an immediate 
invocation of Undo. 


Backspacing 

Regardless of circumstances and context, if the selection is an 
insertion point, pressing the BACKSPACE key deletes one character 
before the insertion point and moves the insertion point to the left of 
the position previously held by that character. This happens during 
editing as well as text entry. 

Pressing BACKSPACE while the selection contains characters operates 
much like a Cut, except that the deleted characters go into the 
backspace buffer (see below) rather than the scrap. The first 
BACKSPACE deletes the selected text, reducing the selection to an 
insertion point; subsequent presses of BACKSPACE operate as described 
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above. 

Every press of BACKSPACE stores up the deleted characters in the 
backspace buffer. Invoking the Undo command reinserts all characters 
in this buffer back into the document at the insertion point. . 
Performing any other operation, such as typing characters or invoking 
another command, clears this buffer; the deleted characters are then 
unrecoverable . 


Cutting and Pasting Between Documents 

Sometimes the user wants to transfer a portion of one document into 
another. The documents may have been created with the same tool, or 
with disparate tools. Macintosh allows this kind of manipulation 
through the mechanism of Cut/Copy and Paste. 


Between Two Documents with the Same Principal Tool 
Transferring information from one document to another created by the 
same application does not pose any difficulty. For example, the user , 
may Copy the return address from 'Letter to Jef' , Get Letter to Linda 
and Paste in the contents of the scrap. 

When the user discards a tool and returns to the Desk, the scrap 
retains not only its contents, but the contextual information pertinent 
to the tool being used. If the user retrieves that same tool, it can 
interpret that information, so there is little or no loss of context 
when carrying something in the scrap from document to document. 


Between Documents with Different Principal Tools 
Macintosh provides a limited but adequate scheme for transferring 
information from a document of one type to a document of another type. 

Suppose the user wants to transfer a picture of a wolf (previously 
created using the Graphics Editor) into a Word Processor document named 
'Letter to Grandma'. Beginning at the Desk, the user gets the wolf 
picture, automatically entering the Graphics Editor. There the picture 
is selected and Cut or Copied into the scrap; then the user returns to 
the Desk. The picture remains in the scrap. 

Now the user calls up the letter to Grandma and enters the Word 
Processor. Upon selecting a position and attempting to Paste, the Word 
Processor examines the scrap and determines whether it is palatable. 

As Graphics Editor pictures are implemented with the QuickDraw picture 
structure, the Word Processor has no problem interpreting and 
displaying the picture, and graciously pastes it into the letter. 
However, in the letter the wolf and the rectangular area around it are 
selectable only as a single unit; the individual parts of the wolf are 
not editable. To the Word Processor the wolf is static data. 

Each tool may have its own appropriate level of interpretation of the 
scrap. If the user tries to Paste the scrap in a tool that does not 
understand it, the tool presents an alert message to inform the user of 
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the undigestability of the scrap. 
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SPECIAL CONDITIONS _ 

The <noun>-Kverb> syntax is wonderful and clean when the operations are 
simple and act on only one object. But occasionally a command will 
require more than one object, or will need additional parameters in 
order to be most useful to the user. And sometimes a command won t be 
able to carry out its normal function, or will be be befuddled as to 
the user's real intent. For these special circumstances we have 
included two mechanisms: the Dialog Box to garner additional 
information, and the Alert mechanism to signal error or warning 
conditions. 


Dialog Boxes ; 

Commands in menus normally act upon only one or two objects: the 
current selection, the scrap, or a default object. If a command needs 
more information before it can be performed, it presents a Dialog Box 
to gather the additional information from the user. 

A Dialog Box is a rectangle that may contain text, buttons, dials, and 
icons. It is slightly below the menu bar, a bit narrower than the 
screen, and as tall as its contents require. It is clearly labelled 
with the name of the command whose invocation prompted the appearance 
of the box. 





Figure 24. A Dialog Box 

Some dialog boxes may affect several properties at the same time or 
show several choices of the same property. In such cases, the choices 
have check-boxes next to them. The boxes next to properties that are 
currently in force are checked. Clicking on a check box or the text 
accompanying it puts a check-mark in the box; this may also cause other 
boxes to become unchecked. 
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If the information requested by the dialog box is textual, the user can 
enter and edit that text just like any other editable text. If the 
information has a default value (which it should have, if possible), 
the default text appears selected in the dialog box. If the user 
starts typing, the selected value will be replaced with what the user 
types. For boxes with many text items, the first one is selected when 
the box appears. After editing an item, 

- Pressing ENTER, TAB, or RETURN accepts the changes made to the 
item, and selects the next item in sequence. 

— Clicking in another item accepts the changes made to the previous 
item and selects the newly clicked item. 

There are, at the absolute minimum, two buttons in the Dialog Box — "OK" 
and "Cancel”. "OK" enforces the modifications in the properties 
included in the Dialog Box, removes the Dialog Box from the screen, and 
performs the command originally issued. "Cancel" dismisses the 
Dialog Box without effecting any changes. 

The "OK" and "Cancel" buttons should always appear in the same relative 
orientation in the Dialog Box to preserve a consistent feel to the 
interaction. They should be near the title of the dialog box to remind 
the user of what command they will perform or cancel. They may be 
marked with reinforcing icons, e.g., thumbs-up and thumbs-down. 

A Dialog Box may include a "Stop" button, marked with an octagonal stop 
sign, for stopping operations that are in progress, such as printing. 

When a command requires some time to execute, its Dialog Box may 
contain a dial that indicates the level of completion of the task in 
progress. 




The Alert Mechanism 

Every user of every application is liable to do something that the 
application won't understand. From simple typographical errors to 
slips of the mouse to trying to write on a protected diskette, users 
will constantly do things an application can't cope with in a normal 
manner. The Alert mechanism gives applications a way to respond to 
errors not only in a consistent manner, but in steps according to the 
severity of the error, the user's level of expertise, and the 
particular history of the error. 

There are three levels of alerts: 


1. Note: Probably a minor slip that's signaled by an audible 
warning. 

2. Caution: A condition in which the application can't understand 
the user's input, and must request that the user change something. 

3. Stop: A situation that requires definitive action on the part of 
the user, such as inserting another diskette. 
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These are ranked in ascending order of importance. Not only are 
program errors ranked in this manner, but repeating an error increases 
its importances receiving the same Note alert several times, for 
example, turns it into a Caution, which warrants further explanation 
and assistance. 

Note alerts are signaled by a beep from the speaker; if the speaker 
volume is turned off, the beep is inaudible. Caution and Stop alerts 
warrant an alert box (see below). 


Alert Boxes 

Alert Boxes are similar in appearance to Dialog Boxes. Alert Boxes are 
intended to give the user warnings and error messages. Before 
describing Alert Boxes it is worth while mentioning a few words about 
alert messages in general. 

Alert Boxes are displayed to: 

- Clarify the system's response to users' actions, (e.g., "This text 
is not editable"), 

- Lead the user through a series of actions required for the 
completion of certain tasks, (e.g. "Please insert a diskette to 
be copied to"), 

- Inform of a state that might affect users' future activities ( The 
document is getting too long to hold in memory. You may want to 
break it up into pieces"), 

- Warn the user against doing something irrevocable or dangerous 
("You will lose the contents of this diskette if you proceed with 
initialization. Do you still want to initialize?"), giving an 
opportunity to cancel the command, and 

- Delay while a lengthy operation is being concluded. 


How to Phrase an Alert Message 

It is important to phrase messages in Alert Boxes so that users are not 
left guessing the real meaning. Do not use computer jargon. Sometimes 
it is difficult for the jaded to recognize jargon even as they use it. 
If you have any doubts of the lucidity of a message, try it on an 
unsuspecting naive friend. 

Use icons whenever possible. Graphics can better describe some error 
situations than words, and familiar icons help users distinguish their 
alternatives better. The thumbs-up icon should always lead to the 
safest route out of a situation. 

Generally, it is better to be polite than abrupt, even if it means 
lengthening the message. The role of the Alert Box is to be helpful 
and make constructive suggestions, not to give out orders. But its 
focus is to help the user solve the problem, not to give an interesting 
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but academic description of the problem itself. 

Under no circumstances should an Alert message refer the user to 
external documentation for further clarification. It should provide a 
complete encapsulation of the information needed by the user to take 
appropriate action. 

(hand) 

The best way to make an Alert message understandable is 
to think carefully through the error condition itself. 

Can the application handle this without an error? Is the 
error specific enough so that the user can fix the 
situation? What are the recommended solutions? Can the 
exact item causing the error be displayed in the alert 
message? 

Be as specific as you can when signaling an error condition. 


Appearance of Alert Boxes 

An Alert Box is a rectangle just a little narrower than the screen and 
of variable height. It may contain text, icons, dials and buttons. It 
appears in a slightly lower position from where Dialog Boxes appear, to 
emphasize that the alert message is more important. 


1 

A 

: 

! 

L_OK_j 

CAUTION! ! 



A A 1 


(CANCEL) 

Your document is setting too large to fit on the 

diskette. Saye it now ttefore £roceedin& i 

IT find 1 

another diskette. 





Figure 25. An Alert Box 

All Alert Boxes have a "Cancel" button that dismisses the box. 

Alert Boxes that require confirmation to perform an action have an 
additional "OK" button. Some Alert Boxes may include a "Stop" button 
to allow the user to interrupt an ongoing operation. As in 
Dialog Boxes, the relative orientation of these buttons should remain 
the same from box to box. 

If there are a small but finite number of ways to solve the problem, 
the box may contain descriptions of those ways, each marked by 
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check-boxes. The user checks the desired solution and presses the "OK" 
button. 

Alert Boxes that require immediate attention contain a stop sign in the 
upper— left corner of the box to emphasize the severity of the warning. 

Alert Boxes that inform the user about a process' status may display 
dials to indicate the level of completion of a task, much as in 
Dialog Boxes. 
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APPENDIX A : THOU-SHALT-NOTS OF A FRIENDLY USER INTERFACE 

Here are six things to avoid when designing a friendly user interface. 

1. Assigning more than one consequence to the same action. 

2. Giving the user several ways to perform the same function. 
Generally, it is much easier for users to learn a task when there 
is only one obvious way of accomplishing it. Too many 
alternatives in an unfamiliar environment may paralyze the user. 

3. Overloading an application with too many esoteric features. 

Before introducing another nifty feature, ask yourself how the 
feature will affect the overall complexity of the application, and 
how many users will benefit from the feature. 

(hand) 

Featurism is the single major contributor to system 
complexity and user intimidation. 

4. Changing the state of the world while the user is not looking. 

One way to make a user comfortable with a system is to create an 
environment that is predictable and consistent. For example, if 
the contents of a menu change from one invocation to another, the 
user comes to think that the machine has a mind of its own, and 
feels that control of it will always be elusive. 

5. Cluttering the screen. A cluttered and busy screen is frequently 
a symptom of an application design that is not carefully thought 
out. Reevaluating the reasons for different features (always 
keeping the end user in mind) will generally result in a simpler, 
more elegant program and visually more streamlined interface. 

6. Overenthusiastic use of modes. It is highly desirable, if not 
always possible, to allow the user to go from one activity to 
another without feeling trapped in a mode. For an eloquent 
discussion of modes, the reader is referred to "The Smalltalk 
Environment", an article by Larry Tesler in the August, 1981 issue 
of BYTE magazine. 
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APPENDIX B ; POINTER SHAPES 

Certain pointer shapes have been standardized to imply that specific 
actions will occur when the mouse button is pushed. 

( I-beam) 

Text selection "J 
(Hollow Cross) 

Selection in a structured document ^ 

(Plus sign) 

Drawing graphics -f- 
( Hourglass) 

Long operation in progress (sometimes associated with a ra 
dial in a dialog box) 


(Arrow) 

All remaining cases, including menus, desk top, graphics 
k selection, button-pushing and dial-dragging, dead data, 
* etc. 
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APPENDIX C : THE PHYSICAL BOX 

The following summarizes Macintosh's salient hardware features. 
Physical box: 

- A main unit with a built-in 9" CRT and a built-in minifloppy 
drive; 

- A detached keyboard; 

- A mouse. 



Memory capacity: 

- 131,072 bytes (128K) of user and program memory, 21,888 bytes (21 
3/8 K) of which are dedicated to the video display; 

- 65,536 bytes (64K) permament (ROM) storage; 

- 860,160 bytes (840K) storage on the built-in disk drive. 
Microprocessor : 

- Sixteen-bit Motorola MC68000 with eight 32-bit data registers, 
seven 32-bit address registers, and two stack pointers. 

- 56 instructions in 14 addressing modes; microprocessor runs at 8 
million cycles per second (8MHz). 

Display: 
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- 512 dots wide, 342 dots tall, black and white dots on a square 
grid. Dots displayed at 80 dots per inch on a 9” screen. 

This is the only configuration of Macintosh. There are no other memory 
sizes, no different ROMs, no other video displays. The consistency of 
the Macintosh user interface is based on the consistency of the 
hardware: as every Macintosh ever sold is guaranteed to contain the 
above, every application program written for this configuration will 
run on 100% of the installed base. 

The only options available are: 

- A second 840K floppy disk drive; 

- An 18-key numeric keypad; 

- A dot-matrix or letter-quality printer; 

- Connection to a RS-232, RS-422, or network communication device. 
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APPENDIX D: KEYBOARD LAYOUTS AND CHARACTER ASSIGNMENTS 


Here are the keyboard layouts and ASCII character assignments for the 
standard character sets in Macintosh: 
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APPENDIX E : GUIDE TO ICONS 

Here are the standard icons as used on our packing materials, on the 
back of the Macintosh itself, and appearing in Macintosh software: 
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APPENDIX F: UNRESOLVED ISSUES 


- What does the Close box do in the main document window for a tool? 
Does it put away the document, unload the tool, and return the 
user to the Desk? As Larry's tests show that users occasionally 
hit the Close box when intending to drag the title bar (or pull 
down a menu) , is it proper for such a commonly-misused icon to 
perform such a time-consuming task? 

- When inactive windows in Lisa are dragged, they are brought to the 
top afterward. We don't do this. 

- Do Show Scrap/Hide Scrap exist? Where? And is the scrap called 
the Clipping? 

- How do Macintosh command-key assignments differ from those on 
Lisa, and will we have a real Apple key rather than the word 
COMMAND? 

- Do Randy's Core Editing or Word Processor routines support 
backspace-by-word, or unbackspace? 

- There's a clash between the use of the stop sign as a warning icon 
in Dialog and Alert Boxes and its use as an icon on the interrupt 
button in the same place. 

- COMMAND- Click and SHIFT-click, and their conflict in the Craphics 
Editor, is unresolved. 

- The l/4 M -grey-around-the-edges was dropped in this draft. It is 
superfluous, hard to code, and adds little to the illusion. 
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These terms are defined here in their technical meaning and 
relationship to one another. Users will never encounter some of the 
terms mentioned here; neither will they read the descriptions as 
phrased here. For a users '-eye-view of Macintosh terminology, please 
see the glossaries in the Macintosh User Style Guide and in the 
Macintosh Introduction manual. 


Active Selection 

(Noun) See Selection, Active 


Active Window 

(Noun) See Window, Active 


Alarm Clock 

(Noun) A desk accessory that displays the 
current date and time, as well as allowing the 
user to set an alarm date and time and an 
alarm message. 

Usage: Same as Desk Accessory 


Alert Box 

(Noun) A window containing warnings and 
cautions, which appears when a tool encounters 
an unsolvable error or a dangerous situation. 
An alert box always contains two buttons, 
labeled OK and Cancel. 

See Also: Alert Message 

Usage: Present an A.B. 


Alert Message 

(Noun) An audible or visible message or 
warning generated by the computer to signal 
input errors, problems interpreting data, or 
situations threatening the safety of the 
user's data. 

See Also: Alert box 


Automatic Scrolling 

Back 

(Noun) See Scrolling, Automatic 

(Noun) The position or orientation of objects 
on the desk furthest from and least visible to 
the user; objects in front overlap and obscure 
objects in the back. 

See Also: Front Window Behind 

Usage: Send to the b. In b. of another 


Behind 

(Adverb) In the position or orientation 
towards the back. An object on the desk is 
behind all the objects that are in front of 
it. 


Button 

(Noun) A control that causes an action when 
clicked or pressed. Buttons highlight when 
pressed. 

Usage: Press Click 
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Button, House 
Calculator 


Cancel button 


Check Box 


Choose 


Click 


Close 


Close Box 


Closed 


Command 


(Noun) See Mouse Button. 

(Noun) A desk accessory that emulates a 
four-function desk calculator. Calculation 
results can be cut and pasted between the 
calculator and the user's document. 

Usage : Same as Desk Accessory 

(Noun) A button that, when pressed, cancels a 
proposed action or action in progress. The 
cancel button is labeled "Cancel 11 and is 
marked with a thumbs-down icon. 

See Also : OK button 
Usage : Same as button 

(Noun) A control in the shape of a square box, 
which may or may not have a check mark in it. 

Clicking in a check box toggles its state, and ^ 

may affect the state of related check boxes. 

Usage : Check Click 

(Verb) To pick a menu item from a menu. 

Usage : Choose a command Choose a menu item 

(Verb) To position the pointer and briefly 
press and release the mouse button without 
moving the mouse. 

See Also : Drag Double-Click 
Usage : Click an object Click the mouse 

button 

(Verb) To remove the window from a document; 
you close a window to reduce it to an icon 
that represents the document. 

Usage : Close a window (never close a file) 

(Noun) The box on the left side of the title 
bar of a document window that, when clicked, 
closes the window. The close box contains an 
icon of a document that "winks" when ckicked. 

Usage : Click the close box 

(Adjective) The state of a window when the 
document it contains is not visible. 

Documents whose windows have been closed are 
represented by icons. 

(Noun) A word (usually appearing as a menu 
item) that describes an action that a 
Macintosh tool can perform; or the action 
itself. 

Usage : Choose a command from a menu The 

command takes effect 
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Control 


Control Panel 


Desk 


Desk Accessories 


Desktop 


Dial 


Dialog Box 


Discontiguous Selection 
Disk 


Disk Drive 


(Noun) An object on the screen that causes an 
action when clicked or dragged; buttons, 
dials, and scroll bars are the most common 
controls. 

Usage : Use only when necessary. 

(Noun) A desk accessory full of controls. 

With it, the user can change the speaker 
volume, the keyboard repeat speed and delay, 
system paranoia level, etc. 

Usage : Same as Desk Accessory 

(Noun) The tool that deals with coying, 
moving, creating, deleting, and changing the 
names of files. Also refers to the smaller 
version used within applications. 

Usage : On the desk (?) 

(Noun) Mini-tools generally available at all 
times. A pocket calculator, note pad, 
telegram form, alarm clock, and the control 
panel are the currently imagined desk 
accessories. 

Usage : Get a D.A. Use the D.A. 

(Noun) The metaphor for the Macintosh working 
environment. 

See Also : Desk 

(Noun) A control that acts as a pseudo-analog 
output and/or input device. 

See Also : Scroll Bar 
Usage : Adjust a dial 

(Noun) A window opened by a tool that requests 
the user for entry or confirmation of 
information. A dialog box is presented when a 
chosen command needs more information in order 
to take effect. 

See Also : Alert Box 

Usage : Present a d.b. Close the d.b. 

(Noun) See Selection, Discontiguous 

(Noun) Any kind of rotating magnetic storage 
device. 

See Also : Diskette Disk Drive 
Usage : Save on a d. Get from a d. 

(Noun) The mechanism that stores and retrieves 
the information on a disk. 

See Also: Diskette 
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Diskette 


Document 


Document Panel 


Document Window 


Double-Click 


Drag 


Enter 


Extend (the Selection) 


File 




(Noun) A thin, plastic disk. 

See Also : Disk Drive 

Usage : Insert the d. Eject the d. On the d. 

(Noun) A collection of information 
intelligible to a user. 

See Also: File Window Tool 

Usage : Get a d. Save a d. Scroll a d. 

(Noun) The pane of a document window that 
presents the document itself , as opposed to 
status panes, formula panes, etc. 

See Also : Panel 

Usage : Avoid if possible. 

(Noun) A window that displays a document. 

Document windows usually come equipped with a 

title bar, one or two scroll bars, a size box, ^ 

and a close box. 

Usage : Use only when "window" is ambiguous. 

(Verb) To click the mouse button again shortly 
after a previous click. Double-clicking an 
object enhances or expands the action normally 
caused by singly clicking that object . 

Usage : D.C. an object D.C. the mouse button 

(Verb) To press and hold the mouse button 
while moving the mouse. Dragging either 
selects items (when done inside the window) or 
drags a flickering outline of an object 
(outside the window). 

See Also: Click Select Choose Size Window 
Split a Window 

Usage: D. an object D. the mouse D. out a 

rectangle D. across the text 

(Verb) To insert or add information into the 
computer, usually by typing on the keyboard. 

Entries are usually terminated by a press of 
the ENTER key. 

Usage : E. the name 

(Verb) To make the active selection larger by 
holding down the COMMAND key while making 
another selection. The two selections and all 
items in between become the new selection. 

See Also: Select Selection 

Usage: Extend the Selection Make an extended 

selection 

(Noun) A storage container for information. 

See Also: Document Tool Window Resource 
File 
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Usage t Delete a f. Copy a f. Move a f. 
Rename a f. 


File 

(Verb) To put a document into a file, or get a 
document from a file* 

File Name 

(Noun) The name attached to a file by its 
creator. 

Font 

(Noun) A set of characters of the same 
typeface and size. 

See Also: Types tyle 

Usage: Appears in the f. 

Front 

(Noun) The position or orientation of objects 
on the desk that are closest and most visible 
to the user; the active window is always in 
front of any other windows. 

See Also: Back Behind 

Usage: Bring to the f. In f. of others 
Frontmost 

Highlight 

(Verb) To emphasize something by making it 
visually distinct from its normal appearance; 
by inverting it, underlining it, making it 
blink, or appear in boldface, etc. 

See Also: Invert Select Front Window 

Usage: H. the text Title bar is highlighted 

Icon 

(Noun) "1. An image; representation. 2. A 
similie or symbol." (AHD) A graphic 
representation of a material object, a 
concept, or a message. Icons may be objects 
on the desk. 

Usage: Click an i. Drag an i. Labeled with 

an i. 

Inactive Selection 

(Noun) See Selection, Inactive 

Inactive Window 

(Noun) See Window, Inactive 

Insertion Point 

(Noun) A selection enclosing nothing; 
indicates the position between two items in a 
document, or an absolute position in that 
document. Indicates the point at which newly 
inserted items will be placed. 

See Also: Select 

Usage: Make an I.P. At the I.P. 

Invert 

(Verb) To invert the black-and-white polarity 
of an image; inverting is the most common form 
of highlighting. 

Usage: Inversely highlighted 
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Itera 


Key 


Keyboard 


Menu 


Menu Bar 


Menu Item 


Menu Title 


Mouse 


Mouse Button 


(Noun) A single piece of information in a 
document. Each character in a text, each 
shape or line in a picture, and each cell in a 
spreadsheet is an item. 

See Also : Select Drag Extend (the 
Selection) 

Usage: Between two items Click an i. Drag 

over items 

(Noun) A button on the keyboard. Character 
keys are typed; modifier keys are held; 
special keys are pressed. 

Usage: Press a k. Hold down a k. 

(Noun) The device used for entering text and 
numeric data. The keyboard has 48 character 
keys, 6 modifier keys, and 4 special keys. 

See Also : Press Type Hold 
Usage : Type on the k. 

(Noun) A rectangular list of menu items, which 
is pulled down from the menu bar; the user 
chooses a menu item by pressing on a menu 
title, dragging through the menu, and 
releasing on a menu item. 

See Also : Command 

Usage: Choose from a m. Pull down a m. 

(Noun) The horizontal strip at the top of the 
screen that contains the menu titles. 

(Noun) One item in a menu. A menu item may 
contain words, an icon, or both. Menu items 
usually describe commands. A menu item is 
highlighted when the pointer is over it. 

See Also : Choose 
Usage : Choose a m. i. 

(Noun) A word or phrase in the menu bar that 
designates one menu. Pressing on the menu 
title pulls down ite menu; dragging through 
the menu highlights menu items. 

Usage : Press on the m. t. 

(Noun) A small device the size of a deck of 
cards that rolls around on your desk. Moving 
the mouse causes corresponding motion of the 
pointer on the screen. 

See Also : Mouse button Drag 
Usage : Move the m. Drag the m. 

(Noun) A rectangular button on the top of the 
mouse. Pressing the button initiates some 
action at the position of the pointer; 
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Note Pad 


Numeric Keypad 


Object 


OK button 


Open (a Window) 


Pane 


Panel 


Pointer 


releasing the button confirms the action. 

See Also : Click Double-click Drag 
Usage : Press the m.b. Release the m.b. 

Click the m.b, 

(Noun) A desk accessory that works as a mini 
word processor, allowing the user to enter and 
edit small amounts of text while working on 
another document. 

Usage : Same as Desk Accessory 

(Noun) An auxilliary keyboard containing keys 
for digits and arithmetic operators, used for 
numeric input. The numeric keypad contains 
sixteen character keys and two special keys. 
See Also : Press Type 
Usage : Same as Keyboard 

(Noun) Anything distinguishable image on the 
desk. Windows, the menu bar, and icons are 
objects. 

See Also : Drag Click Front 

Usage : Click an o. Drag an o. Select an o. 

(Noun) A button that, when pressed, confirms a 
proposed action. The OK button is labeled 
"OK" and is marked with a thumbs-up icon. 

See Also : Cancel button 
Usage : Same as button 

(Verb) To create a window onto a document in 
order to view the information. 

See Also : Close Closed 
Usage : Open a window 

(Noun) A portion of a window with a different 
function or purpose than other panes of the 
same window. The tool defines the panes in 
the window it presents. 

See Also : Panel 

Usage : One pane of the window 

(Noun) A user-definable subdivision of a pane. 
The user creates panels in the document pane 
by using a split bar. 

See Also : Splitting a Window 
Usage : One panel of the window 

(Noun) A small object, usually a 
north-northwest arrow, that hovers above all 
other objects on the screen. It moves around 
as you move the mouse around. 

See Also : Click Drag Press 

Usage : Position the p. by moving the mouse 
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Press 


Principal Tool 
Release 

Resource File 

Scroll 

Scroll Arrow 


Scroll Bar 


Scrolling, Automatic 

Select 




(Verb) 1. To depress the mouse button, 2, To 
depress a special key on the. keyboard. 3. To 
position the pointer with the mouse and 
depress and hold the mouse button. 

See Also: Click Drag Key Release 
Usage : P. the RETURN key P. the mouse button 

P. on a menu title 

(Noun) See Tool, Principal. 

(Verb) To cease pressing. Releasing the mouse 
button quickly, without moving the mouse, 
results in a click. 

See Also : Drag Double-Click 
Usage : R. the mouse button 

(Noun) A file containing information relevant 
to or necessary for the operation of the 
Macintosh or an individual tool. 

Usage : Same as file 

(Verb) To move a document so that a different 
part of it is visible in the window. 

See Also : Scroll Bar Scrolling 
Usage: S. the document 

(Noun) A button at either end of a scroll bar, 
with a picture of an arrow on it. Pressing a 
scroll arrow scrolls the document in its 
direction, and moves the thumb closer to the 
arrow. 

See Also : Scroll 
Usage : Same as button 

(Noun) A rectangular bar along the right or 
bottom edge of a window. Clicking and 
dragging in various parts of the scroll bar 
moves the document in the window, and moves 
the thumb accordingly. 

See Also : Scroll Arrow Shaft Thumb 
Usage : Use the s.b. 

(Noun) The process of scrolling while making a 
selection. 

See Also : Scroll 

(Verb) To click or drag in a collection of 
items or objects, in order to designate them 
to be acted upon by a subsequent command. 

See Also: Selection Insertion Point Extend 
“ “ ““ the Selection 

Usage: S. the text S. a file 
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Selection 


Selection, Active 


(Noun) A collection of text or objects 
designated to be acted upon by a subsequent 
command. The selection appears highlighted in 
the document. 

See Also : Select Highlight Active/ Inactive 
Selection Insertion Point 
Usage : Edit the s. Make a s. 

(Noun) The selection that will be influenced 
by the next command. The active selection is 
always highlighted. 

See Also : Selection, Inactive 

Usage: Use "selection" unless ambiguous. 


Selection, Discontiguous (Noun) A selection whose items are not 

contiguous: that have other, nonselected 

items between two selected items. A 
discontiguous selection is made with the 
assistance of the SHIFT key. 

See Also : Selection Extending the Selection 
Usage : Make a d.s. 


Select ion , Inact ive 


Shaft 


Size 


Size box 


Split a Window 


Split bar 


(Noun) A selection in an inactive window, or 
in a pane of the active window other than the 
pane containing the active selection. 

See Also : Selection, Active 

Usage : Refer to this only when necessary. 

(Noun) The long, thin gray area of the scroll 
bar in which the thumb appears. Clicking in 
the shaft to either side of the thumb moves 
the document one page. 

See Also : Thumb 
Usage : Click in the s. 

(Verb) To change the size of a window by 
dragging its size box. 

Usage : Size a window 

(Noun) A rectangle in the bottom right corner 
of a window containing an icon. Dragging this 
box allows the user to alter the size of the 
window by repositioning its bottom right 
corner. 

See Also : Size 
Usage : Drag the s.b. 

(Verb) To drag a split bar in order to divide 
a window into two panels. 

Usage : Split the Window 

(Noun) A small black bar at one end of a 
scroll bar. Dragging a split bar into the 
window causes the window to be split into two 
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Telegram Form 


Thumb 


Thumb 


Title Bar 


Tool 


Tool, Principal 


Type 


Typeface 


panels at the point where the mouse button was 
released. 

See Also : Split a Window 
Usage : Same as object 

(Noun) A desk accessory that allows the user 
to send or receive messages over the AppleNet 
network. 

Usage : Same as Desk Accessory 

(Noun) The indicator of a scroll bar. The 
position of the thumb within the shaft 
represents the position of the window over the 
length (or breadth) of the document. 

See Also : Thumb (verb) 

Usage : Drag the t. 

(Verb) To move to a different part of the 
document by dragging the thumb, clicking or 
pressing the scroll arrows, or clicking or 
pressing in the shaft. 

See Also : Scroll 

Usage : T. through the document 

(Noun) The horizontal bar at the top of a 
document window. It contains the name of the 
file from which the document in that window 
was taken. On the left side of the title bar 
is the close box. 

Usage : Same as object 

(Noun) A manipulator of information, otherwise 
known as an Application Program. 

See Also : Document File Resource File 
Tool, Principal 
Usage : Get a t. Use a t. 

(Noun) The tool most strongly associated with 
a given document. 

(Verb) To press and release one or more 
character keys on the keyboard or numeric 
keypad. The user types information on the 
keyboard. 

Usage : Type the following Type on the 
keybaord 

(Noun) A collection of letters, digits, 
punctuation marks, and other typographical 
symbols with a coherent "look" and consistent 
design. 

See Also : Types tyle Font 
Usage : Of a t. 
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Typestyle 


Window 


Window, Active 


Window, Inactive 


(Noun) A stylistic variation that can be 
applied to any typeface; examples are 
boldface, italic, underlined, shadowed, and 
outlined. 

See Also : Font Highlight 
Usage : In a t. 

(Noun) A presenter of information. A window 
is an object on the desk. 

See Also : Document Window Tool 
Usage : Open a w. Close a w. Size a w. Drag 
a w. Bring the w. to the front 

(Noun) The frontmost window, which will 
receive commands and data entered. 

See Also : Window, Inactive 

Usage : Use "window" unless ambiguous. 

(Noun) Any visible window other than the 
active window. 

See Also : Window 

Usage : Refer to this only when necessary. 
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ABSTRACT 

Windows play an important part in the Macintosh world, since all informa- 
tion presented by an application appears in windows* The Window Manager 
provides routines for creating and manipulating windows* This manual 
describes those routines along with related concepts and data types. 


Summary of significant changes and additions since last version: 

- Changes have been made to the predefined window definition IDs 
(page 8) and the window classes (page 12). An rDocProc type of 
window no longer requires the corner-rounding in the ref Con field. 

- DrawDocGrow has been replaced by DrawGrowIcon (page 23). 

- A close box or size box appears in active windows only. (See 
FindWindow, page 23, and window definition function, page 35.) 

- The discussions of DragWindow, GrowWindow, and SizeWindow have 
been clarified, and examples have been added for InvalRect and 
ValidRect (page 25). 

- PinRect and DragGrayRgn (formerly DragTheRgn) are now described as 
Window Manager routines rather than Toolbox Utilities (page 30). 

- InsertWindow and DeleteWindow have been removed. 
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ABOUT THIS MANUAL 


This manual describes the Window Manager, a major component of the 
Macintosh User Interface Toolbox. *** Eventually it will become part 
of a large manual describing the entire Toolbox. *** The Window 
Manager allows you to create, manipulate, and dispose of windows in a 
way that’s consistent with the Macintosh User Interface Guidelines. 

( hand ) 

This manual describes version 7 of the ROM. If you’re 
using a different version, the Window Manager may not 
work as discussed here. 

Like all documentation about Toolbox units, this manual assumes you’re 
familiar with the Macintosh User Interface Guidelines, Lisa Pascal, and 
the Macintosh Operating System’s Memory Manager. You should also be 
familiar with the following: 

- The basic concepts and structures behind QuickDraw, particularly 
points, rectangles, regions, graf Ports, and pictures. You don’t 
have to know the QuickDraw routines in order to use the Window 
Manager, though you’ll be using QuickDraw to actually draw inside 
a window. 

- Resources, as discussed in the Resource Manager manual. 

- The Toolbox Event Manager. Some Window Manager routines are 
called only in response to certain events. 

- A Macintosh application that uses windows, as an illustration of 
the window concepts presented here. 

The manual begins with an introduction to the Window Manager and what 
you can do with it. It then discusses the basics about windows: the 
relationship between windows and graf Ports; the various regions of a 
window; and the relationship between windows and resources. Following 
this is a discussion of the window record, where the Window Manager 
keeps all the information it needs about a window. There are also 
sections on what happens when a window is drawn and when a window 
becomes active or inactive. 

Next, a section on using the Window Manager introduces its routines and 
tells how they fit into the flow of your application. This is followed 
by detailed descriptions of all Window Manager procedures and 
functions, their parameters, calling protocol, effects, side effects, 
and so on. 

Following these descriptions are sections that will not interest all 
readers. The exact format of the resource data that defines a window 
is given, followed by special information for programmers who want to 
define their own windows and for those who will use the Window Manager 
routines from assembly language. 
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Finally, there’s a summary of the Window Manager data structures and 
routine calls, for quick reference, and a glossary of terms used in 
this manual* 


ABOUT THE WINDOW MANAGER 


The Window Manager is a tool for dealing with windows on the Macintosh 
screen* The screen represents a working surface or desktop ; graphic 
objects appear on the desktop and can be manipulated with the mouse. A 
window is an object on the desktop that presents information, such as a 
document or a message. Windows can be any size or shape, and there can 
be one or many of them, depending on aesthetics and available memory. 

Some types of window are predefined for you. One of these is the 
standard document window , as illustrated in Figure 1. Every document 
window has a title bar containing a title that’s centered and in the 
system font and system font size. In addition, a particular document 
window may or may not have a close box or a size box; both of these are 
supported by the Window Manager. There may also be scroll bars along 
the bottom and/or right edge of a document window. Scroll bars are 
controls, and are discussed in the Control Manager manual. 



} Title bar 


«- Si2e box 




Figure 1. An Active Document Window 

Your application can easily create predefined types of window such as 
document windows, or it can define its own types of window. Some 
windows may be created indirectly for you when you use other parts of 
the Toolbox; an example is the window the Dialog Manager creates to 
display an alert box. Windows created either directly or indirectly by 
an application are collectively called application windows . There’s 
also a class of windows called system windows , which are not created as 
the result of something done by the application. Desk accessories are 
displayed in system windows. 
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The document window shown in Figure 1 above is the frontmost ( active ) 
window, the one that will be acted on when the user types, gives 
commands, or whatever is appropriate to the application being used* 
Its title is highlighted so it can be distinguished from other, 
inactive windows that may be on the screen* *** Method of 
highlighting will change* *** Since a close box or size box will 
perform its special function only in an active window, neither box 
appears at all in an inactive window (see Figure 2). 




Job Titles 


Memo 



Inactive 

windows 


The 

active 

window 


Figure 2. Overlapping Document Windows 


(hand) 

If a document window has neither a size box nor scroll 
bars, the lines delimiting those areas aren’t drawn, as 
in the Memo window in Figure 2. 

An important function of the Window Manager is to keep track of 
overlapping windows. You can move windows to different places on the 
screen, change their plane (their front-to-back ordering), or change 
their size, all without concern for how the various windows overlap. 

The Window Manager makes sure that any newly exposed areas are redrawn, 
and that the application can draw into any window without running over 
onto windows in front of it. 

Finally, the Window Manager makes it easy for you to set up your 
application so that mouse actions cause these standard responses inside 
a document window, or similar responses inside other windows: 

- Clicking anywhere in an inactive window makes it the active window 
by bringing it to the front and highlighting its title. 

- Clicking inside the close box of the active window makes the 
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window close (so it no longer presents information) or disappear 

altogether* 

- Dragging anywhere inside the title bar of a window (except in the 
close box, if any) pulls an outline of the window across the 
screen* an4 releasing the mouse button moves the window to the new 
location* If the window isn’t the active window, it becomes the 
active window unless the COMMAND key was also held down *** (key 
name may change) ***• A window can never be moved completely off 
the screen; by convention, it can’t be moved such that the visible 
area of the title bar is' less than four pixels square. 

- Dragging inside the size box of the active window changes the size 
of the window. 


WINDOWS AND GRAFPORTS 


It’s easy for applications to use windows: to the application, a 
window is a grafPort that it can draw into like any other with 
QuickDraw routines. When you create a window, you specify a rectangle 
that becomes the portRect of the grafPort in which the window contents 
will be drawn. The bitMap for this grafPort, its pen pattern, and 
other characteristics are the same as the default values set by the 
OpenPort routine in QuickDraw, except for the character font, which is 
set to the application font. These characteristics will apply whenever 
the application draws in the window, and they can easily be changed 
with QuickDraw routines (SetPort to make the grafPort the current port, 
and other routines as appropriate). 

There is, however, more to a window than just the grafPort that the 
application draws in. For example, in a document window, the title bar 
and outline of the window are drawn by the Window Manager, not by the 
application. The part of a window that the Window Manager draws is 
called the window frame , since it usually surrounds the rest of the 
window. The Window Manager draws window frames in a grafPort that has 
the entire screen as its portRect and is called the Window Manager 
port . 


WINDOW REGIONS 


Every window has the following two regions: 

- The content region : the area that the application draws in. 

- The structure region : the entire window; its complete ’’structure” 
(the content region plus the window frame). 

The content region lies within the rectangle you specify when you 
create the window (that is, the portRect of the window’s grafPort); for 
a document window, it’s the entire portRect. This is where information 
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is presented by the application and where the size box and scroll bars 
of a document window are located* Clicking in this region of an 
inactive window makes it the active window. 

A window may also have any of the regions listed below. By convention, 
clicking or dragging in one of these regions causes the indicated 
action. 


- A go-away region within the window frame. Clicking in this region 
of the active window makes the window close or disappear. 

- A drag region within the window frame. Dragging in this region 
pulls an outline of the window across the screen, moves the window 
to a new location, and makes it the active window unless the 
COMMAND key was held down. 

- A grow region , usually within the content region. Dragging in 
this region of the active window changes the size of the window. 

In a document window, the grow region is in the content region, 
but in windows of your own design it may be in either the content 
region or the window frame. 


Figure 3 illustrates the various regions of a document window and its 
window frame. 



Structure region 


= Content region 
+ Window frame 



Content region 


Grow region 


m 


Window frame 


Drag region 


I 

Go-away region 



Figure 3. Document Window Regions and Frame 


An example of a window that has no drag region is the window that 
displays an alert box. On the other hand, you can design a window 
whose drag region is the entire structure region and whose content 
region is empty; such a window might present a fixed picture rather 
than information that’s to be manipulated. 


Another important window region is the update region . The Window 
Manager keeps track of all areas of the content region that have to be 
redrawn, and accumulates them into the update region. For example, if 
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you bring to the front a window that was overlapped by another window, 
the Window Manager adds the formerly overlapped (now exposed) area of 
the front window’s content region to its update region. The update 
region is maintained for the most part by the Window Manager. If a 
window's content region includes a size box or scroll bars, however, 
the application has to manipulate the update region itself to ensure 
that they get redrawn properly; the Window Manager provides update 
region maintenance routines for this purpose. 


WINDOWS AND RESOURCES 


The general appearance and behavior of a window is determined by a 
routine called its window definition function, which is stored as a 
resource in a resource file. Most applications will use the predefined 
window definition functions provided in the system resource file; some 
will write their own window definition functions (as described later in 
the section "Defining Your Own Windows"). 

When you create a window, you specify the type of window with a window 
definition ID . The window definition ID tells the Window Manager the 
resource ID of the definition function for this type of window, and 
also provides some other information. (The details are discussed in 
the section on defining your own windows; you don't have to know them 
to use the predefined window types.) The Window Manager calls the 
Resource Manager to read the window definition function from the 
resource file into memory. Later, when it needs to perform certain 
basic operations such as drawing the window frame, the Window Manager 
calls the window definition function. 


You can use one of the following constants as a window definition ID to 
refer to a predefined type of window: 


CONST documentProc = 0 ; 

dBoxProc = 1 ; 

dBoxZero = 2; 

mdBoxProc = 3; 

rDocProc = 16; 


{standard document window} 

{alert box or modal dialog box} 

{like dBoxProc but with no shadow} 
{modeless dialog box} *** forthcoming *** 
{desk accessory window} 


- The dBoxProc type of window resembles an alert box or a "modal" 
dialog box (the kind that requires the user to respond before 
doing any other work on the desktop). It's a rectangular window 
with no go-away region, drag region, or grow region and with a 
two-pixel- thick "shadow". 


- The dBoxZero type of window is just like the dBoxProc type except 
that it has no shadow. 


- The mdBoxProc type of window looks like a "modeless" dialog box, 
the kind that lets the user work elsewhere on the desktop before 
responding. *** Its exact appearance has yet to be determined. 
*** 
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- The rDocProc type of window is the window used for desk 

accessories. It f s like a document window with no grow region, 
with rounded corners, and with a method of highlighting that 
inverts the entire title bar. 

Rounded-corner windows are drawn by the QuickDraw routine 
Fr ame Round Rect , which requires that the diameters of curvature be 
passed in its ovalWidth and ovalHeight parameters. For an rDocProc 
type of window, the diameters of curvature are both 16. *** A way to 

specify different diameters via the window definition ID is 
forthcoming. *** 

To create a particular window, the Window Manager needs to know not 
only the window definition ID but also other information specific to 
this window, such as its title (if any), its location, and its plane. 
You can supply all the needed information in parameters to a Window 
Manager routine or, better yet, you can store it as a single resource 
in a resource file and pass the resource ID instead. This type of 
resource, which is called a window template , simplifies the process of 
creating a number of windows of the same type. More important, it 
allows you to isolate specific window descriptions from your 
application code. Translation of window titles into a foreign 
language, for example, would require only a change to the resource 
file. 

(hand) 

You can create window templates and store them in 
resource files with the aid of the Resource Editor *** 
eventually (for now, the Resource Compiler) ***. The 
Resource Editor relieves you of having to know the exact 
format of a window template, but for interested 
programmers this information is given in the section 
"Format of a Window Template". 


WINDOW RECORDS 


The Window Manager keeps all the information it requires for its 
operations on a particular window in a window record . The window 
record contains the following: 

- The grafPort for the window 

- A handle to the window definition function 

- A handle to the window* s title, if any 

- A handle to a list of controls, if any, in the window 

- A pointer to the next window in the window list , which is a list 
of all windows ordered according to their f ront-to-back positions 
on the desktop 
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- The window class , which tells whether the window is a system 

window, a dialog or alert window, or a window created directly by 
the application 

The handle to the window’s title has a data type that you may want to 
use yourself elsewhere; it’s defined in the Window Manager as follows: 

TYPE StringPtr = ~Str255; 

StrHandle = ^StringPtr; 

The window record also contains an indication of whether the window is 
currently visible . This means only that the window is drawn in its 
plane, not necessarily that you can see it on the screen. If, for 
example, it’s completely overlapped by another window, it’s still 
’’visible” even though it can't be seen in its current location. 

The reference value field of the window record is a 32-bit field that 
the application may store into and access for any purpose. For 
example, it might contain a handle to data associated with the window, 
such as a TextEdit edit record. 

Finally, a window record may contain a handle to a QuickDraw picture of 
the window contents. The application can swap out the code and data 
that draw the window contents if desired, and instead use this picture. 
For more information, see ”How a Window is Drawn”. 

The data type for a window record is called WindowRecord. A window 
record is a dynamic data structure and is referred to by a pointer, as 
discussed further under ’’Window Pointers” below. You can store into 
and access most of the fields of a window record with Window Manager 
routines, so normally you don’t have to know the exact field names. 
Occasionally — particularly if you define your own type of window you 
may need to know the exact structure; it's given below under "The 
WindowRecord Data Type”. 


Window Pointers _____ 

There are two types of pointer through which windows can be accessed: 
WindowPtr and WindowPeek. Most users will only need to use WindowPtr. 

The Window Manager defines the following type of window pointer: 

TYPE WindowPtr = GrafPtr; 

It can do this because the first thing stored in a window record is the 
window’s grafPort. This type of pointer can be used to access fields 
of the grafPort or can be passed to QuickDraw routines that expect 
pointers to graf Ports as parameters. The application might call such 
routines to draw into the window, and the Window Manager itself calls 
them to perform many of its operations. The Window Manager gets the 
additional information it needs from the rest of the window record 
beyond the grafPort. 
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In some cases, however, a more direct way of accessing the window 
record may be necessary or desirable. For this reason, the Window 
Manager also defines the following type of window pointer: 

TYPE WindowPeek = ^WindowRecord ; 

Programmers who want to access WindowRecord fields directly must use 
this type of pointer (which derives its name from the fact that it lets 
you "peek" at the additional information about the window). A 
WindowPeek pointer is also used wherever the Window Manager will not be 
calling QuickDraw routines and will benefit from a more direct means of 
getting to the data stored in the window record. 

A simple Pascal operation lets you switch from one type of window 
pointer to the other. For example, if wPtr is of type WindowPtr and 
wPeek is of type WindowPeek, you can convert from one type to the other 
as follows: 

wPeek := POINTER(ORD(wPtr ) ) ; {convert from WindowPtr to WindowPeek} 
wPtr := POINTER(ORD(wPeek) ) ; {convert from WindowPeek to WindowPtr} 


(hand ) 

From assembly language, of course, there's no type 
checking on pointers, and the two types of pointer are 
equal. 


The WindowRecord Data Type 

For those who want to know more about the data structure of a window 
record or who will be defining their own types of window, the exact 
data structure is given here. 

TYPE WindowRecord = RECORD 


port: 

Graf Port ; 

windowKind : 

INTEGER; 

visible: 

BOOLEAN; 

hilited: 

BOOLEAN; 

goAwayFlag : 

BOOLEAN; 

spareFlag : 

BOOLEAN; 

strucRgn: 

RgnHandle; 

contRgn : 

RgnHandle ; 

updateRgn: 

RgnHandle ; 

windowDef Proc : 

Handle ; 

dataHandle : 

Handle ; 

titleHandle : 

String Handle ; 

titleWidth: 

INTEGER; 

controlList : 

Handle ; 

nextWindow: 

WindowPeek ; * 

windowPic : 

PicHandle ; 

ref Con: 

Long Int 


END; 


8/25/83 Rose 


CONFIDENTIAL 


/WMGR/ WINDOW. 3 


12 


Window Manager Programmer's Guide 


The port is the window's grafPort. 

WindowKind identifies the window class. If negative, it means the 
window is a system window. It may also be one of the following 
predefined constants : 

dialogKind = 2; {dialog or alert window} 

userKind = 8; {window created directly by the application} 

WindowKind values 1 through 7 are reserved for system use. UserKind is 
stored in this field when a window is created directly by the 
application (rather than indirectly through the Dialog Manager, as for 
dialogKind); for such windows the application can in fact set the 
window class to any value greater than 8 if desired. 

When visible is TRUE, the window is currently visible. 

Hilited and goAwayFlag are checked by the window definition function 
when it draws the window frame, to determine whether the window should 
be highlighted and whether it should have a go-away region. For a 
document window, this means that if hilited is TRUE, the title of the 
window is highlighted, and if goAwayFlag is also TRUE, a close box 
appears in the highlighted title bar. 

SpareFlag is reserved for future use. 

StrucRgn, contRgn, and updateRgn are region handles, as defined in 
QuickDraw, to the structure region, content region, and update region 
of the window. These regions are all in global coordinates. 

The windowDef Proc field contains a handle to the window definition 
function for this type of window. This handle is returned by the 
Resource Manager after it reads the definition function from the 
resource file into memory. From the window definition ID that you 
provide when you create the window, the Window Manager can tell what 
resource ID to pass on to the Resource Manager. 

(hand) 

The high-order byte of the windowDef Proc field contains 
some additional information that the Window Manager gets 
from the window definition ID; for details, see the 
section "Defining Your Own Windows". Also note that if 
you write your own window definition function and won't 
be sharing it with other applications, you can put it in 
with the application code and just store a handle to it 
in the windowDef Proc field. 

DataHandle is reserved for use by the window definition function. If 
the window is one of your own definition, your window definition 
function may use this field to store and access any information it 
wishes. If only four or fewer bytes of information are needed, your 
definition function can store it directly in the dataHandle field 
rather than use a handle. 
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TitleHandle is a stringHandle to the window* s title, if any. 

TitleWidth is the width, in pixels, of the window* s title in the system 
font and system font size. This width is determined by the Window 
Manager and is normally of no concern to the application. 

ControlList is a handle to a list of controls, if any, in the window. 
The Control Manager is responsible for maintaining this list. 

NextWindow is a pointer to the next window in the window list, that is, 
the window behind this window. If this window is the furthest back 
(with no windows between it and the desktop), nextWindow is NIL. 

WindowPic is a handle to a QuickDraw picture of the window contents, or 
NIL if the application will draw the window contents in response to an 
update event, as described under **How a Window is Drawn**, below. 

Ref Con is the window* s reference value field, which the application may 
store into and access for any purpose. 

(hand) 

Notice that the go-away, drag, and grow regions are not 
included in the window record. Although these are 
conceptually regions, they don't necessarily have the 
formal data structure for regions as defined in 
QuickDraw. The window definition function determines 
where these regions are, and it can do so with great 
flexibility. 


HOW A WINDOW IS DRAWN 


When a window is drawn or redrawn, the following two-step process 
usually takes place: the Window Manager draws the window frame and the 
application draws the window contents. 

To perform the first step of this process, the Window Manager calls the 
window definition function with a request that the window frame be 
drawn. It manipulates regions of the Window Manager port as necessary 
before calling the window definition function, to ensure that only what 
should and must be drawn is actually drawn on the screen. Depending on 
a parameter passed to the routine that created the window, the window 
definition function may or may not draw a go-away region in the window 
frame (a close box in the title bar, for a document window). 

Usually the second step is that the Window Manager generates an update 
event to get the application to draw the window contents. It does this 
by accumulating in the update region the areas of the window's content 
region that need updating. The Toolbox Event Manager periodically 
checks to see if there's any window whose update region is not empty; 
if it finds one, it reports (via the GetNextEvent routine) that an 
update event has occurred, and passes along the window pointer in the 
event message. (If it finds more than one such window, it issues an 
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update event for the frontmost one, so that update events are reported 
in f ront-to-back order.) The application should respond as follows: 

1. Call BeginUpdate, a routine that temporarily replaces the visRgn 
of the window’s grafPort with the intersection of the visRgn and 
the update region. 

2. Draw the window contents, entirely or in part. Normally it s more 
convenient to draw the entire content region, but it suffices to 
draw only the update region. In either case, since the visRgn is 
limited to where it intersects the update region, only the parts 
of the window that require updating will actually be drawn on the 
screen. 

3. Call EndUpdate, which restores the normal visRgn and sets the 
update region to the empty region. 

Figure 4 illustrates the effect of BeginUpdate and EndUpdate on the 
visRgn and update region of a window that’s redrawn after being brought 
to the front. 
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Figure 4. Updating Window Contents 


( hand ) 

Although unlikely, it’s possible that a desk accessory 
may not be set up to handle update events, so the 
application may receive an update event for a system 
window. For this reason, it’s a good idea to check 
whether the window to be updated is one that was created 
by your application; if it’s not, just ignore it. 

The Window Manager allows an alternative to the update event mechanism 
that may be useful for simple windows : a handle to a QuickDraw picture 
may be stored in the window record. If this is done, the Window 
Manager doesn’t generate an update event to get the application to draw 
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the window contents; instead, it calls the QuickDraw routine 
DrawPicture to draw the picture whose handle is stored in the window 
record (and it does all the necessary region manipulation). If the 
amount of storage occupied by the picture is less than the size of the 
code and data necessary to draw the window contents, and the 
application can swap out that code and data, this drawing method is 
more economical (and probably faster) than the usual updating process. 


MAKING A WINDOW ACTIVE : ACTIVATE EVENTS 

A number of Window Manager routines change the state of a window from 
inactive to active or from active to inactive. For each such change, 
the Window Manager generates an activate event , passing along the 
window pointer in the event message and, in the modifiers field of the 
event record, bits that indicate the following: 

- Whether this window has become active (bit 0=1) or inactive 
(bit 0=0). 

- Whether the class of the active window is changing from an 
application window to a system window or vice versa. (If so, 
bit 1=1; if no such change is happening, bit 1=0.) 

When the Toolbox Event Manager finds out from the Window Manager that 
an activate event has been generated, it passes the event on to the 
application (via the GetNextEvent routine). Activate events have a 
higher priority than any other type of event. 

Usually when one window becomes active another becomes inactive, and 
vice versa, so activate events are most commonly generated in pairs. 
When this happens, the Window Manager generates first the event for the 
window becoming inactive, and then the event for the window becoming 
active. Sometimes only a single activate event is generated, such as 
when there's only one window in the window list. When the active 
window is permanently disposed of, no activate event is generated to 
report that it's inactive, because the window no longer exists at all. 

Activate events for dialog and alert windows are handled by the Dialog 
Manager. In response to activate events for windows created directly 
by your application, you might take actions such as the following: 

- In a document window containing a size box or scroll bars, erase 
the size box icon or scroll bars when the window becomes inactive 
and redraw them when it becomes active. 

- In a window that contains text being edited, remove the 
highlighting or blinking vertical bar from the text when the 
window becomes inactive and restore it when the window becomes 
active. 

- Enable or disable a menu or certain menu items as appropriate to 
match what the user can do when the window becomes active or 
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inactive . 

( hand ) 

Like update events, activate events for system windows 
may be passed to your application because a desk 
accessory wasn’t set up to handle them* Although this 
will rarely happen, it’s a good idea to check whether the 
window to which the activate event applies is one that 
was created by your application, and ignore it if not. 


USING THE WINDOW MANAGER . 

This section discusses how the Window Manager routines fit into the 

general flow of an application program and gives you an idea of which 

routines you’ll need to use* The routines themselves are described in 

detail in the next section. ^ 

To use the Window Manager, you must have previously called InitGraf to 
initialize QuickDraw and InitFonts to initialize the Font Manager. The 
first Window Manager routine to call is the initialization routine 
InitWindows, which draws the desktop and the (empty) menu bar. 

Where appropriate in your program, use NewWindow or GetNewWindow to 
create any windows you need; these functions return a window pointer, 
which you can then use to refer to the window. NewWindow takes 
descriptive information about the window from its parameters, whereas 
GetNewWindow gets the information from window templates in a resource 
file. You can supply a pointer to the storage for the window record or 
let it be allocated by the routine creating the window; when you no 
longer need a window, call CloseWindow if you supplied the storage, or 
DisposeWindow if not. 

When the Event Manager reports that an update event has occurred, call 
BeginUpdate, draw the update region or the entire content region, and 
call EndUpdate (see ”How a Window is Drawn”, above). You can also use 
InvalRect or InvalRgn to prepare a window for updating, and ValidRect 
or ValidRgn to temporarily protect portions of the window from 
updating. 

When drawing the contents of a window that contains a size box in its 
content region, you’ll draw the size box if the window is active or 
just the lines delimiting the size box and scroll bar areas if it’s 
inactive. The FrontWindow function tells you which is the active 
window; the DrawGrowIcon procedure helps you draw the size box or 
delimiting lines. You'll also call the latter procedure when an 
activate event occurs that makes the window active or inactive. 

( hand) 

To be safe, it’s a good idea to check that an update or 
activate event received by your application applies to 
one of its own windows and not a system window. 




8/25/83 Rose 


CONFIDENTIAL 


/WMGR/WINDOW • 3 


USING THE WINDOW MANAGER 


17 




When a mouse down event occurs, call the FindWindow function to find 
out which part of which window the mouse button was pressed in. 

- If it was pressed in the content region of an inactive window, 
make that window the active window by calling SelectWindow. 

- If it was pressed in the grow region of the active window, call 
GrowWindow to pull around an image that shows the window T s size 
will change, and then SizeWindow to actually change the size. 

- If it pressed in the drag region of any window, call DragWindow, 
which will pull an outline of the window across the screen, move 
the window to a new location, and, if the window is inactive, make 
it the active window (unless the COMMAND key was held down). 

- If it was pressed in the go-away region of the active window, call 
TrackGoAway to handle highlighting of the go-away region and to 
determine whether the mouse is inside the region when the button 
is released. Then do whatever is appropriate as a response to 
this mouse action in the particular application. For example, 
call CloseWindow or DisposeWindow if you want the window to go 
away permanently, or HideWindow if you want it to disappear 
temporarily. 

(hand) 

If the mouse button was pressed in the content region of 
an active window (but not in the grow region), call the 
Control Manager routine FindControl if the window 
contains controls. If it was pressed in a system window, 
call the Desk Manager routine SystemClick. See the 
Control Manager and Desk Manager manuals for details. 

The procedure that simply moves a window without pulling around an 
outline of it, MoveWindow, can be called at any time, as can 
SizeWindow — though the application should not surprise the user by 
taking these actions unexpectedly. There are also routines for 
changing the title of a window, placing a window behind another window, 
and making a window visible or invisible. Call these Window Manager 
routines wherever needed in your program. 


WINDOW MANAGER ROUTINES 


This section describes first the Window Manager procedures and 
functions that are used in most applications, and then the low-level 
routines for use by software developers who have their own ideas about 
what to do with windows. The routines are presented in their Pascal 
form; for information on using them from assembly language, see "Using 
the Toolbox from Assembly Language" *** doesn't exist, but see "Using 
QuickDraw from Assembly Language" in the QuickDraw manual and also 
"Notes for Assembly -Language Programmers" in this manual. *** 
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Initialization and Allocation 


PROCEDURE InitWindows ; 

InitWindows initializes the Window Manager* It creates the Window 
Manager port; you can get a pointer to this port with the GetWMgrPort 
procedure (below). InitWindows draws the gray desktop with rounded 
corners, and a white menu bar with a black line underneath* Call this 
procedure once before all other Window Manager routines* 


PROCEDURE GetWMgrPort (VAR wPort: GrafPtr) ; 

GetWMgrPort returns in wPort a pointer to the Window Manager port* 
(hand) 

Assembly-language programmers can access this pointer 
through the global variable wMgrPort. 


FUNCTION NewWindow (wStorage: Ptr; boundsRect: Rect; title: Str255; 

visible: BOOLEAN; procID: INTEGER; behind: WindowPtr; 
goAwayFlag: BOOLEAN; refCon: Longlnt) : WindowPtr; 

NewWindow creates a window as specified by its parameters, adds it to 
the window list, and returns a WindowPtr to the new window. It 
allocates space for the structure and content regions of the window and 
asks the window definition function to calculate those regions* 

WStorage is a pointer to the storage to use for the window record. For 
example, if you’ve declared the variable wRecord of type WindowRecord , 
you can pass @wRecord as the first parameter to NewWindow* If you pass 
NIL for wStorage, the window record will be allocated on the heap; this 
is not recommended except for programs that have an unusually large 
amount of memory available or have been set up to dispose of windows 
dynamically. 

BoundsRect, a rectangle given in global coordinates, determines the 
window’s size and location* It becomes the port Rect of the window s 
grafPort; note, however, that the portRect is in local coordinates* 

(hand) 

The bitMap , pen pattern, and other characteristics of the 
window’s grafPort are the same as the default values set 
by the OpenPort routine in QuickDraw, except for the 
character font, which is set to the application font 
rather than the system font. 

Title is the window’s title, which appears centered and in the system 
font and system font size in the title bar of a document window* If 
the title of a document window is longer than will fit in the title 
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bar, only as much of the beginning of the title as will fit is 
displayed. 

If the visible parameter is TRUE, NewWindow draws the window. First it 
calls the window definition function to draw the window frame; if 
goAwayFlag is also TRUE and the window is frontmost (as specified by 
the behind parameter, below), it draws a go-away region in the frame. 
Then it generates an update event for the entire window contents. 

ProcID is the window definition ID, which leads to the window 
definition function for this type of window. The window definition IDs 
for the predefined types of windows are listed in the "Windows and 
Resources" section. Window definition IDs for windows of your own 
design are discussed in the section "Defining Your Own Windows". 

The behind parameter determines the window’s plane. The new window is 
inserted in back of the window pointed to by this parameter. To put 
the new window behind all other windows, use behind=NIL. To place it 
in front of all other windows, use behind=POINTER(-l ) ; in this case, 
NewWindow will unhighlight the previously active window, highlight the 
window being created, and generate appropriate activate events. 

Ref Con is the window’s reference value, set and used only by the 
application. 

NewWindow also sets the window class in the window record to indicate 
that the window was created directly by the application. 


FUNCTION GetNewWindow (windowID: INTEGER; wStorage: Ptr; behind: 

WindowPtr) : WindowPtr; 

Like NewWindow (above), GetNewWindow creates a window as specified by 
its parameters, adds it to the window list, and returns a WindowPtr to 
the new window. The only difference between the two functions is that 
instead of having the parameters boundsRect, title, visible, procID, 
goAwayFlag, and refCon, GetNewWindow has a single windowID parameter, 
where windowID is the resource ID of a window template that supplies 
the same information as those parameters. The wStorage and behind 
parameters of GetNewWindow have the same meaning as in NewWindow. 


PROCEDURE CloseWindow (theWindow: WindowPtr); 

CloseWindow removes the given window from the screen and deletes it 
from the window list. It returns to the heap the storage used by all 
data structures associated with the window, but does not dispose of the 
window record itself. Call this procedure when you’re done with a 
window if you supplied NewWindow or GetNewWindow a pointer to the 
window storage (in the wStorage parameter) when you created the window. 

Any update events for the window are discarded. If the window was the 
frontmost window and there was another window behind it, the latter 
window is highlighted and an appropriate activate event is generated. 
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PROCEDURE DisposeWindow (theWindow: WindowPtr); 

DisposeWindow removes the given window from the screen, deletes it from 
the window list, and disposes of the window record. It returns to the 
heap all data structures associated with the window. Call this 
procedure when you’re done with a window if you let the window record 
be allocated on the heap when you created the window (by passing NIL as 
the wStorage parameter to NewWindow or GetNewWindow) . 

Any update events for the window are discarded. If the window was the 
frontmost window and there was another window behind it, the latter 
window is highlighted and an appropriate activate event is generated. 

(hand) 

The macro you invoke to call this routine from assembly 
language is named _JDisposWindow. 


Window Display _ 

These procedures affect the appearance or plane of a window but not its 
size or location. 


PROCEDURE SetWTitle (theWindow: WindowPtr; title: Str255); 

SetWTitle changes the title of theWindow to the given title, performing 
any necessary redrawing of the window frame. If the new title of a 
document window is longer than will fit in the title bar, only as much 
of the beginning of the title as will fit is displayed. 

(hand) 

In a document window, the title is centered in the title 
bar if it fits. If it doesn't fit, it’s left-justified 
(against the close box, if any, leaving a small amount of 
space between the close box and the beginning of the 
title) . 


PROCEDURE GetWTitle (theWindow: WindowPtr; VAR title: Str255); 
GetWTitle returns the title of theWindow. 


PROCEDURE SelectWindow (theWindow: WindowPtr); 

SelectWindow makes theWindow the active window as follows: it 
unhighlights the previously active window, brings theWindow in front of 
all other windows, highlights theWindow, and generates the appropriate 
activate events. Call this procedure if there's a mouse down event in 
the content region of an inactive window. 
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PROCEDURE HideWindow (theWindow: WindowPtr); 


HideWindow makes theWindow invisible if it isn't already invisible and 
has no effect if it is already invisible. If theWindow is the 
frontmost window and there's a window behind it, HideWindow also 
unhighlights theWindow, brings the window behind it to the front, 
highlights that window, and generates appropriate activate events (see 
Figure 5). 
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Figure 5. Hiding and Showing Document Windows 


PROCEDURE ShowWindow (theWindow: WindowPtr); 

ShowWindow makes theWindow visible if it's not already visible and has 
no effect if it is already visible. It does not change the 
front-to-back ordering of the windows. Remember that if you previously 
hid the frontmost window with HideWindow, HideWindow will have brought 
the window behind it to the front; so if you then do a ShowWindow of 
the window you hid, it will no longer be frontmost (see Figure 5 
above ) • 

(hand) 

Although it’s inadvisable, you can create a situation 
where the frontmost window is invisible. If you do a 
ShowWindow of such a window, it will highlight the window 
if it ? s not already highlighted and will generate an 
activate event to force this window from inactive to 
active. 


PROCEDURE ShowHide (theWindow: WindowPtr; showFlag: BOOLEAN); 

If showFlag is FALSE, ShowHide makes theWindow invisible if it’s not 
already invisible and has no effect if it is already invisible. If 
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showFlag is TRUE, ShowHide makes theWindow visible if it’s not already 
visible and has no effect if it is already visible. Unlike HideWindow 
and ShowWindow, ShowHide never changes the highlighting or 
f ront-to-back ordering of windows or generates activate events. 

(eye) 

Use this procedure carefully, and only in special 
circumstances where you need more control than allowed by 
HideWindow and ShowWindow. 


PROCEDURE HiliteWindow (theWindow: WindowPtr; fHilite: BOOLEAN); 

If fHilite is TRUE, this procedure highlights theWindow if it’s not 
already highlighted and has no effect if it is highlighted. If fHilite 
is FALSE, HiliteWindow unhighlights theWindow if it is highlighted and 
has no effect if it’s not highlighted. The exact way a window is 
highlighted depends on its window definition function; a document 
window's definition function highlights only the window's title. 

Normally your application won't have to call this procedure, since it 
should call SelectWindow to make a window active, and SelectWindow 
takes care of the necessary highlighting changes. Highlighting a 
window that isn't the active window is contrary to the Macintosh User 
Interface Guidelines. 


PROCEDURE BringToFront (theWindow: WindowPtr); 

BringToFront brings theWindow to the front of all other windows and 
redraws the window as necessary. Normally your application won't have 
to call this procedure, since it should call SelectWindow to make a 
window active, and SelectWindow takes care of bringing the window to 
the front. If you do call BringToFront, however, remember to call 
HiliteWindow to make the necessary highlighting changes. 


PROCEDURE SendBehind (theWindow: WindowPtr; behindWindow: WindowPtr); 

SendBehind sends theWindow behind behindWindow, redrawing any exposed 
windows. If behindWindow is NIL, it sends theWindow behind all other 
windows. If theWindow is the active window, it unhighlights theWindow, 
highlights the new active window, and generates the appropriate 
activate events. 

(eye) 

Do not use SendBehind to deactivate a previously active 
window. Calling SelectWindow to make a window active 
takes care of deactivating the previously active window. 
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FUNCTION FrontWindow : WindowPtr; 

FrontWindow returns a pointer to the first visible window in the window 
list (that is, the active window). 


PROCEDURE DrawGrowIcon (theWindow: WindowPtr); 

Call this procedure in response to an update or activate event 
involving a window that contains a size box in its content region. If 
theWindow is active (highlighted), DrawGrowIcon draws the size box; 
otherwise, it draws whatever is appropriate to show that the window 
temporarily cannot be sized. The exact appearance and location of 
what f a drawn depend on the window definition function. For an active 
document window, DrawGrowIcon draws the size box icon in the bottom 
right corner of the portRect of the window’s grafPort, along with the 
lines delimiting the size box and scroll bar areas (16 pixels in from 
the right edge and bottom of the portRect). It doesn’t erase the 
scroll bar areas, so if the window doesn’t contain scroll bars you 
should erase those areas yourself after the window’s size changes. For 
an inactive document window, Br-awBocGrcrc* draws only the delimiting 
lines (again, without erasing anything). 


Mouse Location 


FUNCTION FindWindow (thePt: Point; VAR whichWindow: WindowPtr) : 
INTEGER; 


When a mouse down event occurs , the application should call FindWindow 
with thePt equal to the point where the mouse button was pressed (in 
global coordinates, as stored in the where field of the event record). 
FindWindow tells which part of which window, if any, the mouse button 
was pressed in. If it was pressed in a window, whichWindow is set to 
the window pointer; otherwise, it’s set to NIL. The integer returned 
by FindWindow is one of the following predefined constants: 


inDes,k = 0 
inMenuBar = 1 
inSysWipdow = 2 
inContent = 3 
inDrag = 4 
inGrow = 5 
inGoAway = 6 


{none of the following} 

{in the menu bar} 

{in a system window} 

{in the content region (except grow, if active)} 
{in the drag region} 

{in the grow region (active window only)} 

{in the go-away region (active window only)} 


Usually inDesk means that the mouse button was pressed on the desktop, 
outside the menu bar or any windows; however, it may also mean that the 
mouse button was pressed inside a window frame but not in the drag 
region or go-away region of the window. Usually one of the last four 
values is returned for windows created by the application. 
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If the window is a document window that doesn’t contain a 
size box, the application should treat inGrow the same as 
inContent; if it’s a document window that has no close 
box, FindWindow will never return inGoAway for that 
window* 


FUNCTION TrackGoAway (theWindow: WindowPtr; thePt: Point) : BOOLEAN; 

When there’s a mouse down event in the go-away region of theWindow, the 
application should call TrackGoAway with thePt equal to the point where 
the mouse button was pressed (in global coordinates, as stored in the 
where field of the event record). TrackGoAway keeps control until the 
mouse button is released, highlighting the go-away region as long as 
the mouse position remains inside it , and restoring the region to 
normal when the mouse moves outside it* The exact way a window s 
go-away region is highlighted depends on its window definition 
function; the highlighting of a document window’s close box is 
illustrated in Figure 6. *** This method of highlighting may 

change* *** When the mouse button is released, TrackGoAway leaves the 
go— away region in its normal state and returns TRUE if the mouse is 
inside the go-away region or FALSE if it’s outside the region* 


in 

Normal close box 


\ls 

“l“ 


Highlighted close box 


Figure 6. A Document Window’s Close Box 




Window Movement and Sizing 


PROCEDURE Move Window (theWindow: WindowPtr; hGlobal .vGlobal: INTEGER; 
front: BOOLEAN); 

MoveWindow moves theWindow to another part of the screen, without 
affecting its size or plane. The top left corner of the portRect o 
the window's grafPort is moved to the screen point indicated by the 
global coordinates hGlobal and vGlobal. If the front parameter is TRUE 
and theWindow isn't the active window, MoveWindow makes it the active 
window by calling SelectWindow( theWindow) • 
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PROCEDURE DragWindow (theWindow: WindowPtr; startPt: Point; boundsRect: 

Rect) ; 

When there's a mouse down event in the drag region of theWindow, the 
application should call DragWindow with startPt equal to the point 
where the mouse button was pressed (in global coordinates, as stored in 
the where field of the event record). DragWindow pulls a gray outline 
of theWindow around, following the path of the mouse until the button 
is released. When the mouse button is released, DragWindow moves 
theWindow to the location to which it was dragged (by calling 
MoveWindow). If theWindow is not the active window and the COMMAND key 
was not being held down, DragWindow makes it the active window (by 
passing TRUE for the front parameter when calling MoveWindow). 

If the mouse button is released when the mouse position is outside the 
limits of boundsRect, a rectangle given in global coordinates, 
DragWindow returns without moving theWindow or making it the active 
window. Typically boundsRect will be (4,24,508,338), which is four 
pixels in from the menu bar and from the other edges of the screen; 
this ensures that there won't be less than a four-pixel-square area of 
the title bar visible on the screen. 


FUNCTION GrowWindow (theWindow: WindowPtr; startPt: Point; sizeRect: 

Rect) : Longlnt; 

When there's a mouse down event in the grow region of theWindow, the 
application should call GrowWindow with startPt equal to the point 
where the mouse button was pressed (in global coordinates, as stored in 
the where field of the event record). GrowWindow pulls a grow image of 
the window around, following the path of the mouse until the button is 
released. The grow image for a document window is a gray outline of 
the entire window and also the lines delimiting the title bar, size 
box, and scroll bar areas; Figure 7 illustrates this for a document 
window containing a size box and scroll bars , but the grow image would 
be the same even if the window contained no size box, one scroll bar, 
or no scroll bars. In general, the grow image is defined in the window 
definition function and is whatever is appropriate to show that the 
window's size will change. 
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si2e returned in 
high-order word 


size returned in low-order word 

Figure 7. GrowWindow Operation on a Document Window 

The application should subsequently call SizeWindow (see below) to 
change the portRect of the window* s grafPort to the new one outlined by 
the grow image. The sizeRect parameter specifies limits, in pixels, on 
the vertical and horizontal measurements of what will be the new 
portRect. SizeRect. top is the minimum vertical measurement, 
sizeRect . left is the minimum horizontal measurement, sizeRect .bottom is 
the maximum vertical measurement, and sizeRect .right is the maximum 
horizontal measurement. 

GrowWindow returns the actual size for the new portRect as outlined by 
the grow image when the mouse button is released. The high-order word 
of the Longlnt is the vertical measurement in pixels and the low-order 
word is the horizontal measurement. A return value of 0 indicates that 
the size is the same as that of the current portRect. 

(hand) 

The Toolbox Utility function HiWord takes a long integer 
as a parameter and returns an integer equal to its 
high-order word; the function LoWord returns the 
low-order word. 



PROCEDURE SizeWindow (theWindow: WindowPtr; w,h: INTEGER; f Update: 

BOOLEAN) ; 

SizeWindow enlarges or shrinks the portRect of theWindow* s grafPort to 
the width and height specified by w and h, or does nothing if w and h 
are 0. The window's position on the screen does not change. The new 
window frame is drawn; if the width of a document window changes, the 
title is again centered in the title bar, or is truncated at its end if 
it no longer fits. If f Update is TRUE, SizeWindow accumulates any 
newly created area of the content region into the update region (see 
Figure 8); normally this is what you'll want. If you pass FALSE for 
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f Update, you’re responsible for the update region maintenance yourself* 
For more information, see InvalRect and ValidRect below. 


After SizeWindo^wPtr, wl, hi, TRUE) 



Ares marked 
is accumulated 
into update region 


i 


wl 


Figure 8. SizeWindow Operation on a Document Window 


(eye) 

You should change the window's size only when the user 
has done something specific to make it change. 


Update Region Maintenance 


PROCEDURE InvalRect (badRect: Rect); 

InvalRect tells the Window Manager that a rectangle within a window has 
changed and must be updated (that is, accumulated into the window's 
update region). The specified rectangle, which is given in local 
coordinates, lies within the content region of the window whose 
grafPort is the current port. 

Normally the Window Manager keeps track of what has to be updated and 
so there's no need to use this procedure. One case where it's useful 
is when you're calling SizeWindow (described above) for a document 
window that contains a size box or scroll bars. Suppose you're going 
to call SizeWindow with fUpdate=TRUE. If the window is enlarged as 
shown in Figure 8 above, you'll want not only the newly created part of 
the content region to be updated , but also the two rectangular areas 
containing the (former) size box and scroll bars; before calling 
SizeWindow, you can call InvalRect twice to accumulate those areas into 
the update region. In case the window is made smaller, you'll want the 
new size box and scroll bar areas to be updated, and so can similarly 
call InvalRect for those areas after calling SizeWindow. See Figure 9 
for an illustration of this type of update region maintenance. 
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Before SizeWindow with f Update = TRUE : 

In case the window is enlarged, 

call InvalRect for 

The original window and I 


After SizeWindow: 

mmZ In case the window was made smaller, 

call InvalRect for jl 


The new window and l 1 3 

Figure 9* Update Region Maintenance with InvalRect 

As another example, suppose the application uses a QuickDraw routine to 
scroll up text in a document window and wants to show new text added at 
the bottom of the window* It can use a drawing routine to draw the 
window, or it can instead cause only the added text to be redrawn, by 
accumulating that area into the update region with InvalRect* 


PROCEDURE InvalRgn (badRgn: RgnHandle); 

InvalRgn is the same as InvalRect (see above) but for a region that has 
changed rather than a rectangle. 


PROCEDURE ValidRect (goodRect: Rect); 

ValidRect tells the Window Manager that the application has already 
drawn a rectangle within a window and to cancel any updates accumulated 
for that area (that is, remove goodRect from the window's update 
region)* The specified rectangle, which is given in local coordinates, 
lies within the content region of the window whose grafPort is the 
current port* Using ValidRect results in better performance and less 
redundant redrawing in the window* 

For example, suppose you've called SizeWindow (described above) with 
fUpdate=TRUE for a document window that contains a size box or scroll 
bars* Depending on the dimensions of the newly sized window, the new 
size box and scroll bar areas may or may not have been accumulated into 
the window's update region* After calling SizeWindow, you can redraw 
the size box or scroll bars immediately and then call ValidRect for the 
areas they occupy in case they were in fact accumulated into the update 
region; this will avoid redundant drawing. 
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PROCEDURE ValidRgn (goodRgn: RgnHandle); 

ValidRgn is the same as ValidRect (see above) but for a region that has 
been drawn rather than a rectangle. 


PROCEDURE BeginUpdate (theWindow: WindowPtr); 

When an update event occurs for theWindow, call BeginUpdate to replace 
the visRgn of the window’s grafPort with the intersection of the visRgn 
and the update region. You would then usually draw the entire content 
region, though it suffices to draw only the update region; in either 
case, only the parts of the window that require updating will actually 
be drawn on the screen. Every call to BeginUpdate must be balanced by 
a call to EndUpdate (see below, and see "How a Window is Drawn"). 


PROCEDURE EndUpdate (theWindow: WindowPtr); 

Call EndUpdate to restore the normal visRgn of theWindow 1 s grafPort, 
which was changed by BeginUpdate as described above. EndUpdate also 
sets theWindow' s update region to the empty region. 


Miscellaneous Utilities 


PROCEDURE SetWRefCon (theWindow: WindowPtr; data: Longlnt); 

SetWRefCon changes the reference value associated with theWindow to the 
given data. 

FUNCTION GetWRefCon (theWindow: WindowPtr) : Longlnt; 

GetWRefCon returns the reference value associated with theWindow. 


PROCEDURE SetWindowPic (theWindow: WindowPtr; pic: PicHandle); 

SetWindowPic stores the given picture handle in the window record for 
theWindow, so that when theWindow' s contents are to be drawn the Window 
Manager will draw this picture rather than generate an update event. 


FUNCTION GetWindowPic (theWindow: WindowPtr) : PicHandle; 

GetWindowPic returns the handle to the picture that draws theWindow' s 
contents, previously stored with SetWindowPic (above). 
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FUNCTION PinRect (theRect: Rect; thePt: Point) : Longlnt; 

PinRect ’’pins” thePt inside theRect: The high-order word of the value 
returned is the vertical coordinate of thePt or, if thePt lies to the 
left or the right of theRect, the vertical coordinate of the left or 
right edge of theRect, respectively. The low-order word of the value 
returned is the horizontal coordinate of thePt or, if thePt lies above 
or below theRect , the horizontal coordinate of the top or bottom of 
theRect. 


FUNCTION DragGrayRgn (theRgn: RgnHandle; startPt: Point; 

limitRect ,slopRect : Rect; axis: INTEGER; actionProc: 

ProcPtr) : Longlnt; 

Called when the mouse button is down inside theRgn, DragGrayRgn pulls a 
gray outline of the region around, following the path of the mouse 
until the button is released* DragWindow calls this function before 
actually moving the window, and the Control Manager routine DragControl 
similarly calls it for controls. You can call it yourself to pull 
around the outline of any region, and then use the information it 
returns to determine where to move the region. 

The startPt parameter is assumed to be the point where the mouse button 
was originally pressed, in the local coordinates of the current 
grafPort. The high-order word of the value returned by DragGrayRgn 
contains the vertical coordinate of the ending mouse point minus that 
of the original point; the low-order word contains the difference 
between the horizontal coordinates. 

LimitRect and slopRect should also be in the local coordinates of the 
current grafPort. LimitRect limits the travel of the region’s outline; 
DragGrayRgn will never move the mouse position outside this rectangle. 
If the mouse button is released outside limitRect, DragGrayRgn returns 
-32768 (hexadecimal 8000). SlopRect allows the user some ’’slop” in 
moving the mouse; it should completely enclose limitRect. 

DragGrayRgn ’ s behavior while tracking the mouse depends on the position 
of the mouse with respect to these two rectangles. 

- When the mouse is inside limitRect, the region’s outline follows 
it normally. If the mouse button is released there, the region 
should be moved to the mouse position. 

- When the mouse is outside limitRect but inside slopRect, the 
outline ’’pins” at the edge of limitRect. If the mouse button is 
released there, the region should be moved to this ’’pinned” 
location. 

- When the mouse is outside slopRect, the outline disappears from 
the screen, but DragGrayRgn continues to follow the mouse; if it 
moves back into slopRect, the outline reappears. If the mouse 
button is released outside slopRect, the region should not be 
moved from its original position. 
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The axis parameter allows you to constrain the outline’s motion to only 
one axis: 


Axis parameter 
0 
1 
2 


Meaning 
No constraint 
Horizontal motion only 
Vertical motion only 


If an axis constraint is in effect, the outline will follow the mouse’s 
movements along the specified axis only, ignoring motion along the 
other axis. With or without an axis constraint, the mouse must still 
be inside the slop rectangle for the outline to appear at all. 


The actionProc parameter is a pointer to a procedure that defines some 
action to be performed repeatedly for as long as the user holds down 
the mouse button; the procedure should have no parameters. If 
actionProc is NIL, DragGrayRgn simply retains control until the mouse 
button is released, performing no action while the mouse button is 
down. 


(hand) 

Assembly-language programmers who want the region’s 
ou tline to be drawn in a pattern other than gray can 
store the pattern in the low— memory global dragPattern 
and call the above function at the entry point 
DragTheRgn. 


Low-Level Rou t ine s 


These low-level routines are not normally used by an application but 
may be of interest to advanced programmers. 


FUNCTION CheckUpdate (VAR theEvent : EventRecord) : BOOLEAN; 

CheckUpdate is called by the Toolbox Event Manager. From the front to 
the back in the window list, it looks for a visible window that needs 
updating (that is, whose update region is not empty). If it finds one 
whose window record contains a picture handle, it draws the picture 
(doing all the necessary region manipulation) and looks for the next 
visible window that needs updating. If it ever finds one whose window 
record doesn’t contain a picture handle, it stores an update event for 
that window in theEvent and returns TRUE. If it never finds such a 
window, it returns FALSE. 


PROCEDURE ClipAbove (window: WindowPeek) ; 

ClipAbove sets the clipRgn of the Window Manager port to be the grayRgn 
(that is, the desktop) intersected with the current clipRgn, minus the 
structure regions of all the windows above the given window* 
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PROCEDURE PaintOne (window: WindowPeek; clobbered: RgnHandle); 

PaintOne paints the given window, clipped to the clobbered region and 
all windows above it* If some content is exposed, PaintOne erases it 
and adds it to the update region. If the window is NIL, it’s painted 
gray (it's the desktop). This procedure generates update events as 
appropriate. 


PROCEDURE PaintBehind (startWindow: WindowPeek; clobbered: RgnHandle); 

PaintBehind calls PaintOne (above) to paint startWindow and all the 
windows behind startWindow, clipped to the clobbered region. 


PROCEDURE SaveOld (window: WindowPeek); 

SaveOld saves the given window’s current structure region and content 
region for the DrawNew operation (see below). It must be followed by a 
call to DrawNew. Note that SaveOld and DrawNew are NOT nestable. 


PROCEDURE DrawNew (window: WindowPeek; update: BOOLEAN); 

DrawWindow is called after SaveOld (above). It updates the area 
clobbered := (oldStruct XOR newStruct) UNION (oldContent XOR 
newContent). If update is TRUE, updates are accumulated. 


PROCEDURE CalcVis (window: WindowPeek); 

CalcVis calculates the visRgn of the given window by starting with its 
content region and subtracting the structure region of each window in 
front of it. 


PROCEDURE CalcVisBehind (startWindow: WindowPeek; clobbered: 
RgnHandle) ; 

CalcVisBehind calculates the visRgns of startWindow and all windows 
behind startWindow that intersect with the clobbered region. It’s 
called after PaintBehind (see above). 

(hand) 

The macro you invoke to call this routine from assembly 
language is named _CalcVBehind • 


FORMAT OF A WINDOW TEMPLATE ___ 

As described above, the GetNewWindow function takes the resource ID of 
a window template as a parameter, and gets from that template the same 
information that the NewWindow function gets from six of its 
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parameters* The resource type for a window template is 'WIND', and the 
resource data has the following format: 


Number of bytes 
8 bytes 
2 bytes 
2 bytes 
2 bytes 
4 bytes 
n bytes 


Contents 

Same as boundsRect parameter to NewWindow 
Same as procID parameter to NewWindow 
Same as visible parameter to NewWindow 
Same as goAwayFlag parameter to NewWindow 
Same as refCon parameter to NewWindow 
Same as title parameter to NewWindow 
(1-byte length in bytes, followed by 
the characters of the title) 


DEFINING YOUR OWN WINDOWS 


Certain types of window, such as the standard document window, are 
predefined for you* However, you may want to define your own type of 
window-may be a round or hexagon-shaped window, or even a window shaped 
like an apple. QuickDraw and the Window Manager make it possible for 
you to do this* 

(hand) 

For the convenience of the application's end user, 
remember to conform to the Macintosh User Interface 
Guidelines for windows as much as possible. 

To define your own type of window, you must write a window definition 
function. Usually you'll store the definition function in a resource 
file. When you create a window, you provide a window definition ID, 
which leads to the window definition function. The window definition 
function contains routines that define the window by performing basic 
operations such as drawing the window frame. When the Window Manager 
needs to perform one of these operations, it calls the window 
definition function with a parameter that identifies the operation, and 
the window definition function in turn takes the appropriate action. 

The window definition ID contains the resource ID of the window 
definition function in its upper 12 bits and a variation code in its 
lower four bits. The variation code allows a single window definition 
function to implement several related types of window as "variations on 
a theme". For example, the dBoxProc type of window is a variation of 
the standard document window; both use the window definition function 
whose resource ID is 0, but the document window has a variation code of 
0 while the dBoxProc window has a variation code of 1. 

For a given resource ID and variation code, then, the window definition 
ID is: 


16 * resource ID + variation code 
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The resource ID numbers 0 through 8 are reserved for predefined window 
definition functions in the system resource file. Unless you want to 
override one of the predefined functions, the resource ID you choose 
for your own window definition function should be greater than 8. 

The resource type for window definition functions is ’WDEF’. The 
Dialog Manager calls the Resource Manager to access the resource of 
type ’WDEF’ that has the given resource ID. The Resource Manager reads 
the window definition function into memory and returns a handle to it. 
The Window Manager stores the handle in the windowDef Proc field of the 
window record and stores the variation code in the high-order byte of 
that field. Later, when it needs to call the window definition 
function, it passes the variation code as a parameter. Figure 10 
illustrates this process. 

Window definition ID supplied when window is created: 

(resource ID of window 
definition function 
and variation code) 


resourcelD 

var 

* ) 

V 


12 bits 

4 bits 


Resource Manager call made by Window Manager: 

defHandle = GetResource ('WDEF', resourcelD); 


Field in window record: 


var 


defHandle 




passed to window definition function 


Figure 10. Window Definition Handling 


(hand) 

If you won’t be sharing your window definition function 
with other applications, you may want to store it in with 
the application code rather than as a separate resource. 

When creating the window, you would give the window 
definition ID of any standard type of window and specify 
that the window not be made visible. Then you would 
replace the contents of the windowDef Proc field with the 
handle (and variation code, if any) for your window 
definition function. 

The resource data for a window definition function is simply the 
assembled code of the function, which may be written in Pascal or 
assembly language; the only requirement is that its entry point must be 
at the beginning. 
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Format of a Window Definition Function 






You may choose any name you wish for the window definition function. 
Here’s how you would declare one named MyOwnWindow: 

FUNCTION MyOwnWindow (varCode: INTEGER; window: WindowPtr; 

message: WindowMessage ; param: Longlnt) : Longlnt; 

VarCode is the variation code, as described above. 

The window parameter indicates the window that the operation will 
affect. If the window definition function needs to use a WindowPeek 
type of pointer more than a WindowPtr, you can simply specify 
WindowPeek instead of WindowPtr in the function declaration. 


The message parameter identifies the operation. 

TYPE WindowMessage * (wDraw, wHit, wCalcRgns, wNew, wDispose, 
wGrow, wDrawGIcon); 


Message 

wDraw 

wHit 

wCalcRgns 

wNew 

wDispose 

wGrow 

wDrawGIcon 


Operation 

Draw the window frame 

Tell what region the mouse button was pressed in 
Calculate the strucRgn and contRgn 
Do any special window initialization 

Take any special actions when the window is disposed of 
Draw the window’s grow image 

Draw the window’s size box in its content region 


As described below in the explanations of the routines that perform 
these operations, the value passed for param, the last parameter of the 
window definition function, depends on the operation. Where it’s not 
mentioned below, this parameter is ignored. Similarly, the window 
definition function is expected to return a value only where indicated; 
in other cases, the function should return 0. 

(hand) 

"Routine” here does not necessarily mean a procedure or 
function. While it’s a good idea to set these up as 
subprograms inside the window definition function, you’re 
not required to do so. 


The Draw Window Frame Routine 


When the window definition function receives a wDraw message, it should 
draw the window frame in the current grafPort, which will be the Window 
Manager port. (For details on drawing, see the QuickDraw manual.) 

(eye) 

Do not change the visRgn or clipRgn of the Window Manager 
port, or overlapping windows may not be handled properly. 
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This routine should make certain checks to determine exactly what it 
should do. If the visible field in the window record is FALSE, the 
routine should do nothing; otherwise, it should examine the value of 
param received by the window definition function, as described below. 

If param is 0, the routine should draw the entire window frame# If the 
hilited field in the window record is TRUE, the window frame should be 
highlighted in whatever way is appropriate to show that this is the 
active window. If goAwayFlag in the window record is also TRUE, the 
highlighted window frame should include a go-away region; this is 
useful when you want to define a window such that a particular window 
of that type may or may not have a go-away region, depending on the 
situation. 

Special action should be taken if the value of param is wlnGoAway (a 
predefined constant, equal to A, which is one of those returned by the 
hit routine as described below). If param is wlnGoAway, the routine 
should do nothing but "toggle 1 * the state of the window's go-away region 
from normal to highlighted or, if it's already highlighted, from 
highlighted to normal. The highlighting should be whatever is 
appropriate to show that the mouse button has been pressed inside the 
region. Simple inverse highlighting may be used or, as in document 
windows, the appearance of the region may change considerably. In the 
latter case, the routine should use a "mask" consisting of the normal 
state of the region Xor'ed with its highlighted state (where Xor stands 
for the logical operation "exclusive or"). When such a mask is itself 
Xor'ed with either state of the region, the result is the other state; 
Figure 11 illustrates this. 


Normal 

state 



y._ \l/ = 

X0 /|\ 

Highlighted 

state 


m 

'I s - 


Mask 



\l/ 


\l/ 

'I' 


Xor 



Figure 11. Toggling the Go-Away Region 

Typically the window frame will include the window's title, which 
should be in the system font and system font size for consistency with 
the Macintosh User Interface Guidelines. The Window Manager port will 
already be set to use the system font and system font size. 
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(hand) 

Nothing drawn outside the window 1 s structure region will 
be visible. 


The Hit Routine 


When the window definition function receives a wHit message, it also 
receives as its param value the point where the mouse button was 
pressed. This point is given in global coordinates, with the vertical 
coordinate in the high-order word of the Longlnt and the horizontal 
coordinate in the low-order word. The window definition function 
should determine where the mouse button "hit" and should return one of 
these predefined constants: 


wNoHit * 0 
wlnContent = 1 
wlnDrag = 2 
wlnGrow = 3 
wlnGoAway ~ 4 


{none of the following} 

{in the content region (except grow, if active)} 
{in the drag region} 

{in the grow region (active window only)} 

{in the go-away region (active window only)} 


Usually, wNoHit means the given point isn't anywhere within the window, 
but this is not necessarily so. For example, the document window's hit 
routine returns wNoHit if the point is in the window frame but not in 
the title bar. 


The constants wlnGrow and wlnGoAway should be returned only if th$ 
window is active, since the size box and go-away region won't be drawn 
if the window is inactive. In an inactive document window, if the 
mouse button is pressed where the close box would be if the window were 
active, the hit routine returns wlnDrag. 

Of the regions that may have been hit , only the content region 
necessarily has the structure of a region and is included in the window 
record. The hit routine can determine in any way it likes whether the 
drag, grow, or go-away region has been hit. It can, for example, 
simply compare the coordinates of the given point to the coordinates of 
the points that delimit a particular region. Or the application can 
use the formal region data structure if desired, and point at it 
through the dataHandle field of the window record. 


The Routine to Calculate Regions 

The routine executed in response to a wCalcRgris message should 
calculate the window's structure region and content region based on the 
current grafPort's portRect. These regions, whose handles are in the 
strucRgn and contRgn fields, are in global coordinates. The Window 
Manager will request this operation only if the window is visible. 

(hand) 

When you calculate regions for yovar own type of window, 
do not alter the clipRgn or the visRgn of the window's 
grafPort. The Window Manager and QuickDraw take care of 
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this for you. Altering the clipRgn or visRgn may result 
in damage to other windows. 


The New Window Routine 

A wNew message tells the window definition function to execute a new 
window* 1 routine that does any special initialization which may be 
required when the window is created. For example, if the content 
region is unusually shaped, it might allocate space for the region and 
store the region handle in the dataHandle field of the window record. 
The **new window” routine for a document window does nothing. 


The Dispose Routine 

The routine executed in response to a wDispose message should take any 
special actions that may be required when the window is disposed of 
(with the Window Manager routine CloseWindow or DisposeWindow) It 
might, for example, deallocate space that was allocated by the new 
window” routine. The dispose routine for a document window does 
nothing. 


The Grow Routine - 

When the window definition function receives a wGrow message, it also 
receives a pointer to a rectangle as its param value. The rectangle is 
in global coordinates and is usually aligned at its top left corner 
with the portRect of the window* s grafPort. The grow routine should 
draw a grow image of the window to fit the given rectangle (that is, 
whatever is appropriate to show that the window’s size will change, 
such as an outline of the content region). The Window Manager requests 
this operation repeatedly as the user drags inside the grow region. 

The grow routine should draw in the current grafPort, which will be the 
Window Manager port, and should use the grafPort *s current pen pattern 
and pen mode, which are set up (as gray and notPatXor) to conform to 
the Macintosh User Interface Guidelines. 

The grow routine for a document window draws a gray outline of the 
window and also the lines delimiting the title bar, size box, and 
scroll bar areas. 


The Draw Size Box Routine. — — 

Thw wDrawGIcon message tells the window definition function to draw the 
size box (’’grow icon”) in the content region of the window if the 
window is active (highlighted) or, if the window is inactive, whatever 
is appropriate to show that it temporarily can’t be sized. For active 
document windows, this routine draws the size box icon in the bottom 
right corner of the portRect of the window's grafPort, along with the 
lines delimiting the size box and scroll bar areas; for inactive 
windows, it draws just the delimiting lines. 
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(hand) 

If the size box is located in the window frame rather 
than the content region, this routine should do nothing. 


NOTES FOR ASSEMBLY-LANGUAGE PROGRAMMERS 


*** This will be moved into a separate chapter of the final 
comprehensive manual. For now, see the QuickDraw manual for complete 
information about how to use the User Interface Toolbox from assembly 
language. *** 

The primary aid to assembly-language programmers is a file named 
ToolEqu.Text. If you use .INCLUDE to include this file when you 
assemble your program, all the Window Manager constants, locations of 
system globals, and offsets into the fields of structured types will be 
available in symbolic form. 
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SUMMARY OF THE WINDOW MANAGER 


CONST documentProc = 0; 


dBoxProc = 1 ; 

dBoxZero ® 2;. 

mdBoxProc = 3; 

rDocProc = 16; 

dialogKind = 2 ; 
userKind = 8; 

inDesk =0; 

inMenuBar = 1 ; 
inSysWindow = 2 ; 
inContent = 3 ; 
inDrag = 4 ; 

inGrow = 5 ; 

inGoAway = 6 ; 

wNoHit = 0; 

wlnContent = 1; 
w InDrag = 2; 
wlnGrow = 3 ; 
w InGoAway = 4 ; 


{standard document window} 

{alert box or modal dialog box} 

{like dBoxProc but with no shadow} 

{modeless dialog box} *** forthcoming *** 
{desk accessory window} 

{dialog or alert window} 

{window created directly by the application} 

{none of the following} 

{in the menu bar} 

{in a system window} 

{in the content region (except grow, if active)} 
{in the drag region} 

{in the grow region (active window only)} 

{in the go-away region (active window only)} 

{none of the following} 

{in the content region (except grow, if active)} 
{in the drag region} 

{in the grow region (active window only)} 

{in the go-away region (active window only)} 


TYPE StringPtr 

StringHandle 


~Str255; 

^StringPtr; 


WindowPtr = GrafPtr; 

WindowPeek = ~WindowRecord ; 


WindowRecord 


RECORD 


port : 

windowKind : 
visible : 
hilited: 
goAwayFlag : 
spareFlag: 
strucRgn: 
contRgn: 
updateRgn: 
windowDef Proc 
dataHandle : 
titleHandle : 
titleWidth: 
controlList : 
nextWindow: 
windowPic: 
ref Con: 


Graf Port ; 

INTEGER; 

BOOLEAN; 

BOOLEAN; 

BOOLEAN; 

BOOLEAN; 

RgnHandle ; 

RgnHandle ; 

RgnHandle; 

Handle ; 

Handle ; 

StringHandle 

INTEGER; 

Handle ; 

WindowPeek; 

PicHandle ; 

Longlnt 


END; 


WindowMessage = (wDraw, wHit, wCalcRgns, wNew, wDispose, wGrow, 
wDrawGIcon) ; 
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Initialization and Allocation 


PROCEDURE InitWindows; 
PROCEDURE GetWMgrPort 
FUNCTION NewWindow 


FUNCTION Get NewWindow 

PROCEDURE CloseWindow 
PROCEDURE DisposeWindow 


(VAR wPort : GrafPtr); 

(wStorage: Ptr; boundsRect: Rect; title: Str255; 
visible: BOOLEAN; procID: INTEGER; behind: 
WindowPtr; goAwayFlag: BOOLEAN; ref Con: Longlnt) 
: WindowPtr; 

(windowID: INTEGER; wStorage: Ptr; behind: 

WindowPtr) : WindowPtr; 

( theWindow : WindowPtr ) ; 

(theWindow: WindowPtr); 


Window Display 

PROCEDURE SetWTitle 
PROCEDURE GetWTitle 
PROCEDURE SelectWindow 
PROCEDURE HideWindow 
PROCEDURE ShowWindow 
PROCEDURE ShowHide 
PROCEDURE HiliteWindow 
PROCEDURE Br ing To Fr on t 
PROCEDURE SendBehind 
FUNCTION FrontWindow : 
PROCEDURE DrawGrowIcon 


(theWindow: 
( theWindow: 
(theWindow: 
( theWindow: 
(theWindow: 
( theWindow: 
(theWindow: 
( theWindow: 
(theWindow: 

WindowPtr; 

(theWindow: 


WindowPtr; title: Str255); 

WindowPtr; VAR title: Str255); 
WindowPtr) ; 

WindowPtr) ; 

WindowPtr) ; 

WindowPtr ; showFlag : BOOLEAN) ; 
WindowPtr; fHilite: BOOLEAN); 
WindowPtr) ; 

WindowPtr; behindWindow: WindowPtr) ; 
WindowPtr) ; 


Mouse Location 


FUNCTION FindWindow (thePt: Point; VAR whichWindow: WindowPtr) 

: INTEGER; 

FUNCTION TrackGoAway (theWindow: WindowPtr; thePt: Point) : BOOLEAN; 


Window Movement and Sizing 

PROCEDURE MoveWindow (theWindow: WindowPtr; hGlobal ,vGlobal : INTEGER; 

front: BOOLEAN); 

PROCEDURE DragWindow (theWindow: WindowPtr; startPt: Point; boundsRect: 

Rect); 

FUNCTION GrowWindow (theWindow: WindowPtr; startPt: Point; sizeRect: 

Rect) : Longlnt; 

PROCEDURE SizeWindow (theWindow: WindowPtr; w,h: INTEGER; f Update: 

BOOLEAN) ; 
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Update Region Maintenance 


PROCEDURE InvalRect 
PROCEDURE InvalRgn 
PROCEDURE ValidRect 
PROCEDURE ValidRgn 
PROCEDURE BeginUpdate 
PROCEDURE EndUpdate 


(badRect: Rect); 
(badRgn: RgnHandle) ; 
(goodRect: Rect); 
(goodRgn: RgnHandle) ; 

( theWindow: WindowPtr ) ; 
( theWindow : WindowPtr ) ; 


Miscellaneous Utilities 


PROCEDURE SetWRefCon 
FUNCTION GetWRefCon 
PROCEDURE SetWindowPic 
FUNCTION GetWindowPic 
FUNCTION PinRect 
FUNCTION DragGrayRgn 


(theWindow: WindowPtr; data: Longlnt); 
(theWindow: WindowPtr) : Longlnt; 

(theWindow: WindowPtr; pic: PicHandle); 
(theWindow: WindowPtr) : PicHandle; 

(theRect: Rect; thePt: Point) : Longlnt; 
(theRgn: RgnHandle; startPt: Point; limitRect, 
slopRect : Rect; axis: INTEGER; actionProc: 
ProcPtr) : Longlnt; 


Low-Level Routines 


FUNCTION CheckUpdate 
PROCEDURE ClipAbove 
PROCEDURE PaintOne 
PROCEDURE PaintBehind 
PROCEDURE SaveOld 
PROCEDURE DrawNew 
PROCEDURE CalcVis 
PROCEDURE CalcVisBehind 


(VAR theEvent : EventRecord) : BOOLEAN; 

(window: WindowPeek) ; 

(window: WindowPeek; clobbered: RgnHandle); 
(startWindow: WindowPeek; clobbered: RgnHandle); 
(window: WindowPeek) ; 

(window: WindowPeek; update: BOOLEAN); 

(window: WindowPeek) ; 

(startWindow: WindowPeek; clobbered: RgnHandle); 


8/17/83 Rose 


CONFIDENTIAL 


/ WMGR/ WINDOW. G 


GLOSSARY 


43 


GLOSSARY 


activate event: An event generated by the Window Manager when a window 
changes from active to inactive or vice versa# 

active window: The frontmost window on the desktop. 

application window: A window created as the result of something done 
by the application, either directly or indirectly (as through the 
Dialog Manager). 

content region: The area of a window that the application draws in. 

desktop: The screen as a surface for doing work in Macintosh. 

document window: A standard Macintosh window for presenting a 
document . 

drag region: A region in the window frame. Dragging inside this 
region moves the window to a new location and makes it the active 
window unless the COMMAND key was down. 

go-away region: A region in the window frame. Clicking inside this 
region of the active window makes the window close or disappear. 

grow image: The image pulled around when dragging inside the grow 
region occurs; whatever is appropriate to show that the window's size 
will change. 

grow region: A window region, usually within the content region, where 
dragging changes the size of an active window. 

inactive window: Any window that isn't the frontmost window on the 
desktop. 

modal dialog: A dialog that requires the user to respond before doing 
any other work on the desktop. 

modeless dialog: A dialog that allows the user to work elsewhere on 
the desktop before responding. 

plane: The f ront-to-back position of a window on the desktop. 

reference value: In a window record, a 32-bit field that the 
application may store into and access for any purpose. 

structure region: An entire window; its complete "structure". 

system window: Any window that isn't created as the result of 
something done by the application. Desk accessories are displayed in 
system windows. 
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update event: An event generated by the Window Manager when the update 
region of a window is to be drawn. 

update region: A window region consisting of all areas of the content 
region that have to be redrawn. 

variation code: A number that distinguishes closely related types of 
windows and is passed as part of a window definition ID when a window 
is created. 

visible window: A window that's drawn in its plane on the desktop (but 
may be completely overlapped by another window). 

window: An object on the desktop that presents information, such as a 

document or a message. 

window class: An indication of whether a window is a system window, a 
dialog or alert window, or a window created directly by the 
application. 

window definition function: A function called by the Window Manager 
when it needs to perform basic operations on a particular type of 
window, such as drawing the window frame. 

window definition ID: A number passed to window-creation routines to 
indicate the type of window. It consists of the window definition 
function's resource ID and a variation code. 

window frame : The structure region minus the content region. 

window list: A list of all windows ordered according to their 
f ront-to-back positions on the desktop. 

Window Manager port: A grafPort that has the entire screen as its 
portRect and is used by the Window Manager to draw window frames. 

window record: The internal representation of a window, where the 
Window Manager stores all the information it needs for its operations 
on that window. 

window template: A resource that contains information from which the 
Window Manager can create a window. 
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This glossary is included to give you a reference to the terms you’ll be 
using when you write about a Macintosh tool. You can refer to it to 
confirm the meaning, spelling, usage, or punctuation of a term. The terms 
included here apply to "end-user" audiences, people who probably have no 
computer background. 

How To Use This 
Glossary" 


Before you do any writing, we recommend you read through the glossary to 
get an idea of what terms are included. Most terms are defined and give a 
usage example. Other terms are qualified: 


Don't use: 

The term is inappropriate for Macintosh end-user programs. Either its 
meaning is too technical for our audience, it has become a computer 
"cliche" whose meaning is obscure, or it belongs to the ranks of 
unfriendly jargon. 


Avoid : 

Don’t use the term if possible. Use the alternate term instead. 
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accessory 




Any piece* of equipment which connects to the Macintosh main unit, except 
the keyboard or the mouse. Sometimes called devices or peripheral 
devices. Macintosh accessories include additional disk drive, keypad, 
and dot-matrix printer. 

See Also: desk, accessory, device 


active selection 

The selection that will be affected by the next command. The active 
selection is highlighted. 

See Also: inactive selection, highlight 
Usage: Use selection unless ambiguous. 


active window 

The frontmost window which receives commands and data entered. The active 
window ’s title appears highlighted. 

See Also: inactive window 


alert box 

A window that appears on the screen containing a warning message. An 
alert box appears when a program encounters an error or a dangerous 
situation. 


alert message 

A message or warning contained in an alert box. It can be an audible 
beep, indicating a warning. An alert message may result from input 
errors, problems interpreting data, or situations threatening the safety 
of the user’s data. Users must respond to an alert message before they 
can proceed. 

See Also: alert box ^ 


Alpha Lock key 

Don’t use. Use Caps Lock key. 


Apple key 

A key on the Macintosh keyboard. The Apple key is held down while 
pressing another key, causing a command to take effect. 
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application program 

Don’t us^; use program. 


application software 

One or more programs using the system’s capabilities to do some 
particular task, such as text processing or data base management. 

See Also : program 

Usage: Avoid this term. Instead, use ’’program" or the program’s name, 
such 

as Macwriter. 


assembly language 

The adjective form is assembly-language. Avoid references to assembly 
language and assembly-language programming in end-user manuals. 


ASCII 

American Standard Code for Information Interchange. Use abbreviation 
only after first reference. Avoid this term. 


automatic scrolling 

The process of scrolling while making a selection. Use only to explain 
the phenomenon. 

See Also: scroll 


back 

The position of objects on the desk furthest from the user. Objects in 
front may overlap and obscure objects in the back. 

See Also: front, window, behind 

Usage: Send to the back. In back of another. 


Backspace key 

A key on the Macintosh keyboard that backspaces over and erases the 
previously typed character. 


back up 

To make copies of disks or documents. 
Usage: Avoid in favor of "Make a copy”. 
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bar 




A rectangular strip on the screen where text is entered and can be edited. 
When the entry is confirmed, the text appears in its intended place, and 
the bar goes away. Bars are usually given names, such as the formula bar 
in Macplan. 

See Also: pane 


BASIC 

A computer language. Acronym for Beginners All-purpose Symbolic 
Instruction Code (no apostrophe), which you do not need to introduce. Use 
Macintosh BASIC to differentiate from other BASICS. 


black-and-white 

Note hyphenation. 

Usage: Macintosh has a black-and-white screen. 


black-on-white 

Don’t use. 

bit 

Don’t use. 


blinking 

Use instead of ”f lashing”. 

Usage: The insertion point is indicated by a blinking vertical bar. 


board 

Part of the Macintosh’s internal structure. Don’t use. 


boot 

Don’t use, use start up. 


buffer 

An area of the Macintosh random-access memory reserved for a specific 
purpose, such as to hold screen images to be sent to a printer. Avoid 
this term. 
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bug 

Don’t \is&- 




button 

A control that causes an action when clicked. Buttons appear in alert and 
dialog boxes and are sometimes used to confirm or cancel ah action. 

See Also: control 
Usage: Click the button. 


button, mouse 

See mouse button. 




byte 

Don’t use. 


cable 

A wire or group of wires that connects a Macintosh and one of its 
accessories. Use cord for connecting between a Macintosh or Macintosh 
accessory and its power source. 

See Also : cord 

Usage: Printer cable, modem cable, disk drive cable. 


cancel 

An unconditional, permanent halt of a specific activity. 


Caps Lock key 

A key on the Macintosh keyboard that, when engaged, causes all typed 
letters to appear uppercase. 


cell 

A container of information in a spreadsheet program. A cell displays its 
value, which may be text, a number, or a formula. Cells are arranged in 
rows and columns. 


character 

A letter, number, or punctuation mark. Be specific when possible. 
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check box 


A control in the shape of a box, which may or may not have an "x" in it. 
Clicking in a check box reverses its state and may affect the state of 
related check boxes. 


choose 

To pick a menu item from a menu. 
Usage : Choose a command 


click 

To position the pointer over an area or object and briefly press and 
release the mouse button without moving the mouse. 

See Also: drag, press, double-click 

Usage: Click an insertion point, click the mouse button. 


Clipboard 

A place that holds information which has been cut or copied. The 
information remains there until the next cut or copy. Note 
capitalization. 


dose (a document) 

To remove the window from a document; you close a window to reduce it to 
an icon that represents the document. 


close box 

An icon on the left side of the title bar of a document window; when 
clicked, the window closes. 

See Also: document window, close, open 
Usage: Click the close box. 


column 

Do not use as a synonym for character position. Okay to use when 
referring to a spreadsheet or other program that uses columns of cells. 


coniand 

A word, usually a menu item, describing an action that a Macintosh program 
can perform. 



computer 


The physical box, including the case and what's inside. Don't use as a 
synonym for Macintosh. 

See Also: system 


connector 

Be specific: 

Usage : 

plug - connector with prongs or pins 
nine-pin plug 
eleven-pin plug 

socket - connector with holes 
nine-pin socket 
eleven-pin socket 

jack - small, round one-pin socket 

Don't use "male" or "female" to describe types of connectors. 

See Also: cable, cord, rear panel diagram 


copy-protected 

Always hyphenated. Some programs have software "locks" on them so they 
can't be copied. These programs are copy-protected. 


cord 

Connects a device to its power source. 

See Also: cable 

Usage: The Macintosh power cord connects to the power plug on the 
rear panel. 


cursor 

Don't use. Use pointer, or the specific pointer's name; hourglass 
pointer, I-beam pointer. 


data 

Avoid in favor of information. DB-11 connector, 

DB-9 connector 

Don't use; use eleven- or nine-pin socket or plug. 
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dealer 


A business or store authorized to sell and service the Macintosh and other 
Apple products. 


dealership 

Don’t use. Use dealer instead. 

default 

Don’t use. 

delete 

Don’t use. Instead, use cut for removing text from a document, or use 
backspace to backspace over a previously typed character. 


Delete key 

Don’t use; use backspace or Backspace key. 


desk accessories 

Functions available to all programs. A calculator, note pad, telegram 
form, and alarm clock are the currently imagined desk accessories. 
Usage: Get a desk accessory. Use the desk accessory. 


desktop 

The gray surface of the Macintosh screen. All programs work on the 
desktop. Anything on the screen appears on the desktop. 


Desktop Manager 

The program that allows users to copy, move, create, delete, print, and 
change the names of files. 


device 

Try to avoid. A physical piece of equipment capable of sending or 
receiving information. Devices include the Macintosh screen, keyboard, 
external disk drive, and printer. 

Usage: Use ’’accessory” or the specific device name rather than ’’device”. 



dialog box 


A window -that requests information or clarification of a command. A 
dialog box is presented by a program when a command needs more information 
or confirmation to take effect. 

See Also: alert box 
Usage: Present a dialog box. 


dialog message 

The message presented in a dialog box. It can include buttons, dials, 
check boxes, and blanks to enter information. 


digit 

A single number, such as 1, 2, or 3# Don't use when you mean number. A 
number is composed of one or more digits. 


dimmed menu item 

A menu item that appears "dim" compared to other menu items. A dimmed 
item cannot be chosen because it’s not appropriate. 


disk 

Any kind of rotating magnetic storage device. 

See Also: disk drive 

Usage: Don't use diskette. Use an article when appropriate: the disk, 
a disk. Never use as an abbreviation for disk drive. 


disk drive 

The mechanism that stores and retrieves the information on a disk. 


display 

Don't use when you mean the screen. Okay to use as a verb, "windows are 
displayed on the screen". 


display screen 

Don't use, use screen, or Macintosh screen. 
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document 


A collection of Information. A document appears in a window; its contents 
are stored in a file on a disk. 

See Also: file, window 
Usage: Get 


document window 

A window that displays a document. 

See Also: window, document 

Usage: Use only when "window" is ambiguous. 


double-click 

Note hyphenation. Clicking (briefly pressing and releasing) shortly after 
a previous click. Double-clicking an object enhances or expands the 
action normally caused by singly clicking that object; it can also be an 
"expert" command. Note: don’t use a hyphen when using as a noun. 

See Also: click 

Usage: Double-click (something) 


drag 

To press and hold the mouse button while moving the mouse. Depending on 
where the pointer is when the mouse button is pressed, dragging either 
selects items or drags a flickering outline of an object. Releasing the 
mouse button after a drag either confirms a selection, moves an object to 
a new location, or does nothing, if the button is released at the same 
location as it was first pressed. 

See Also: click, mouse, select, choose, press, size 

Usage: Drag an object, drag the pointer. Drag out a rectangle. 

Drag across the text. Never: drag the mouse. 


drive 

Use disk drive except in passages where the full term becomes cumbersome. 


embolden 

Don’t use. 


Enter key 

A key on the Macintosh keyboard. Pressing the Enter key confirms or 
terminates an entry. 

Usage: Press the Enter key. 



enter 


To inserts or add information into a Macintosh program, usually by typing 
on the keyboard. 

Usage: Enter the name. 


extend a selection 

To make the active selection larger by holding down the Apple key while 
making another selection. The two selections and all items in between 
become the new selection. 

See Also: select, selection 

Usage: Extend the selection, make an extended selection. 


female connector 

Don’t use; use socket or specific socket name. 


field-action keys 

Arrow-like keys on the optional numeric keypad. Never call them arrow or 
cursor keys. 


file 

A container of information. Use only to refer to a collection of 
information stored as a named unit on a disk. 

See Also: document, resource, window, program 
Usage: Remove, copy, move, rename a file. 


file name 

The name that the creator of a file has attached to it. The Desktop 
Manager displays the names of all files on a disk. 


flashing 

Don’t use; use blinking. 
See Also : highlight 


format 

To prepare a disk to receive information. 
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front 


The position or orientation of the object on the desk that is closest to 
the user; the active window is always in front of any other windows. 

See Also: back, behind, active window 
Usage: Bring to the front. In front of. 


get 

To bring a file into a program from the disk. 
Usage: Get a file, get what file? 


graphic 

(adj.) The description of the Macintosh screen. 


graphical 

Don’t use; use graphic. 


graphics 

The display of images on the Macintosh screen. Also, information 
presented in the form of pictures. 

Usage: Takes a singular verb. 


gray 

The appearance or "color 11 of portions of the Macintosh screen. The high 
resolution Macintosh screen allows many shades of gray, from light gray to 
dark gray. 


halt 

Don’t use; use cancel. 


hard disk 

A rotating device with several surfaces for recording information 
magnetically. A hard disk is enclosed in a protective box. 


highlight 

The state of an object or selection which is visually distinct from its 
normal form. Common methods of highlighting include: inverting the 
object or selection, underlining, or making an object blink. 

See Also: select, invert, front, window 



Usage: .The text appears highlighted. 


highlighted 

The state of an active selection or the front window. Don't use as a 
verb. 

See Also: highlight 

Usage: The title bar is highlighted. 


icon 

A graphic representation of an object, a concept, or a message. A symbol 
with evident meaning. Icons are often objects on the desk, such as closed 
windows • 

Usage: Click, drag an icon. Labeled with an icon. 


inactive selection 

A selection in an inactive window or another pane of the active window. 
See Also: active selection 
Usage: Avoid this distinction. 


inactive window 

Any window other than the active window. 

See Also : window 

Usage: Don't use unless "window" alone is ambiguous. 


input 

Information entered from the keyboard, modem, disk drive, or mouse. 
Usage: Avoid this term. Never use as a verb. 


Insertion point 

The position between two items in a document. The insertion point is 
represented by a blinking vertical bar. While there is an insertion 
point, any typed text appears between the two items designated by the 
insertion point. 

See Also: selection, item 

Usage: Make an insertion point. At the insertion point. 


interactive 

Don't use. 
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invert 


To reverse the black-and-white polarity of an image* Inverting is the 
most common form of highlighting* Do not use "displayed in inverse"* 
See Also: highlight 
Usage: Avoid in favor of highlight. 


item 

See menu item. 


key 

A button on the keyboard. Character keys are typed , modifier keys are 
held , special keys are pressed . 

Usage: Press, hold a key. 


keyword 

A special word in a programming language that identifies a particular type 
of statement or command, such as IF or CATALOG. 


kilobyte 

Don f t use • 


load 

Don’t use; use get or read. 


male connector 

Don't use; use plug or specific plug name. 


menu 

A list of commands that appears when a user points to and presses the menu 
title in the menu bar. Dragging through the menu and releasing over a 
command (called a menu item) chooses that item. 

See Also: menu bar, menu title, drag, command 
Usage: Choose from a menu. 


menu bar 

The horizontal strip at the top of the screen that contains menu titles 
See Also: menu, menu title, menu item, press 



Usage: Press in the menu bar. 


menu item 

One line of a menu. A menu item may contain words, an icon, or both. 
Menu items are usually commands. 

See Also: menu, menu bar, menu title, command 
Usage: Choose a menu item. 


menu title 

A word or phrase in the menu bar that designates one menu. Pressing on 
the menu title causes the title to highlight and its menu to appear below. 
Dragging through the menu and releasing over an item chooses a menu item. 
See Also: menu, menu bar, menu item 
Usage: Press on the menu title. 


mode 

A state of the system that determines its response to the user's actions. 
Avoid unless absolutely necessary. Macintosh has been designed to avoid 
modes. Do not use the word "mode" to describe something that really isn't 
one. 


mouse 

A small device the size of a deck of cards that you roll around on a flat 
surface next to your Macintosh. Moving the mouse causes corresponding 
motion of the pointer on the screen. Avoid the plural form "mice" • Avoid 
mouse puns (never dangle your mouse by the tail). 

See Also: pointer, mouse button, drag 
Usage: Move the mouse. 


mouse button 

The square button on the top of the mouse. Pressing the mouse button 
initiates some action on the object under the pointer; releasing the 
button confirms the action. Always refer to as the "mouse button", never 
just "button". 

See Also: double-click, pointer, mouse, click, press, drag 
Usage: Press, click, or release the mouse button. 


numeric keypad 

An accessory keyboard containing number and arithmetic-operator keys; used 
for numeric input. 
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open (a document ) 


To create* a window onto a document to view the information. You open an 
icon into a document to view the document. 

See Also: close, window, document 


Option key 

A key that is used like the Shift key. Using the Option key gives an 
alternate interpretation for the key typed. It may be used for foreign 
characters or special symbols. 


output 

Do not use; instead: write or save (to), display (on), or print (to). 


palette 

A menu always present on the screen. The MacPaint screen has a palette of 
drawing shapes. 

Usage: Select the airbrush from the palette by clicking it. 


pane 

A portion of a window with a different function or purpose than other 
portions of the same window. A window usually consists of one pane, but 
the program can define more than one pane in a window it presents. 

See Also: window, split 
Usage: One pane of a window. 


Pascal 

A programming language. Note capitalization. 

See Also : accessory 

Usage: Be specific when possible 

UCSD Pascal. 


peripheral device 

Avoid in favor of accessory. Never use "peripheral" as a noun. 


plug 

A connector with prongs or pins. Be specific; it's not a "plug", but a 
"mouse plug". 

See Also: connector, socket 



point 


To position the pointer over a specific location on the screen. 
See Also: drag, click, pointer 
Usage: Point at the menu title. 


pointer 

A small shape on the screen, most often an arrow pointing up and left, 
that follows the motion of the mouse. The pointer is always in front of 
everything else on the desktop. 

See Also: mouse, click, drag, press 

Usage: Position the pointer by moving the mouse. 


power cable 

Don f t use; use power cord. 


power cord 

The cord which connects a Macintosh or Macintosh accessory to its power 
source. 

See Also : cable 


power receptacle 

A recessed plug on the rear of the Macintosh where the power cord 
attaches. 


press 

1. To depress a key on the keyboard that is not a character key (character 
keys are typed). 2. To position the pointer and depress and hold the 
mouse button. A press can become a click if the mouse button is 
immediately released, or a drag if the user moves the mouse. 

See Also: click, drag, type 

Usage: Press the Return key. Press the mouse button. Press on a menu 
title. 

Never: press a button on the screen. 


procedure 

A routine that can be called from any point in a program and returns 
control to the point of call upon completion. 

Usage: Avoid this term. 


APPENDIX A — The Macintosh Writer’s Glossary 17 



processor 


One component of the computer. The Macintosh processor is the Motorola 

68000. 

Usage: Avoid this term. 


program 

A single, self-contained piece of software, otherwise known as an 
application program. Use !, program n or the specific program name instead 
of application program. 

See Also: document, file, resource 
Usage: Get 


programmer 

One who writes programs. Refer to specific types of programmers: game 
programmers, system programmers, Macintosh programmers. 


prompt 

Do not use as an noun. Try to avoid as a verb: "The system is prompting 
you for inf ormation”. "Ask" is better. 


protect 

Use instead of lock. You remove protection (from a file, document, or 
disk), not unlock or unprotect. 


pull-down 

Don’t use as a verb when talking about menus. Ok to use as an adjective 
for menus: ”pull-down menu”. Don't use in place of menu ("pull-down”). 
See Also: menu, press, choose 


put back 

To close a document. RAM, 


random-acce8smemory 

Note hyphenation. A computer’s working memory. Use RAM only after first 
introducing random-access memory. 



To transfer the contents of a file into memory. After the file is in 
memory, it is called a document. 

Usage: Don’t use read unless you are referring to the specific 
process of copying the file from disk into memory. Instead use "get a 
document" . 


read-onlymemory 

Note hyphenation. Memory whose contents can be read but not changed. 
Information is written into read-only memory during the manufacturing 
process. Use ROM only after first reference. The Macintosh ROM contains 
the operating system. 

Usage: Avoid introducing this term. 


release 

To cease pressing a key or the mouse button. 

See Also: drag, double-click, click 

Usage: Release the mouse button. Release over a menu item. 


Return key 

A key on the Macintosh keyboard that adds a new line in a document or 
terminates an entry. Note capitalization. 

Usage: Press the Return key. 


ROM 

See read-only memory. 


routine 

Avoid this term. A portion of a program that accomplishes some specific 
task. Routines can be either functions or procedures. Try to be specific 
and use procedure or function instead of routine. 


run 

Don’t use; use start. 

save 

1. To write information to a disk. 2. A menu item in some programs which 
means to write the current state of a document to a file on a disk. 
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scroll 




To move a document so that a different part of it is visible in the 
window* 

See Also: scroll bar 
Usage: Scroll the document. 


scroll arrow 

A button at either end of a scroll bar, with an arrow on it. Pressing a 
scroll arrow moves the window in the direction of the arrow, and moves the 
scroll box closer to the arrow* 

See Also: scroll bar, scroll box, scroll 
Usage: Same as button* 


scroll bar 

A rectangular bar that may be at the right and/or bottom of a window. 
Clicking and dragging in various parts of the scroll bar moves the window 
over the document, and moves the scroll box accordingly. 

See Also: click, drag, press, scroll arrow, shaft, scroll box 
Usage: Use the scroll bar. 




scroll box 

The white box on the scroll bar. Dragging the scroll box moves the 
document under the window. 


scrolling, automatic 
See automatic scrolling. 


select 

To click or drag over characters in a document, or click a window or an 
icon in order to designate them to be acted upon by a subsequent command. 
See Also: selection, insertion point, extend the selection, choose 
Usage: Select text. Select a document. You don’t select a menu item; 

you choose a menu item. 


selection 

The window, characters, or icon(s) to be affected by the next command. 

The selection appears highlighted. 

See Also: select, highlight, insertion point, active, inactive selection 
Usage: Edit the selection. Make a selection. 
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serial interface 


An interface through which information is transmitted sequentially, one 
bit at a time, over a single wire. The Macintosh’s accessory connectors 
are serial interfaces. Only mention if necessary. 

Shiftkey 

Pressing the Shift key gives the upper character on two-character keys, or 
the upper-case letter. Note capitalization. 

See Also: Caps Lock 

shiftlock 

Don’t use. Use Caps Lock. 


size 

To change the size of a window by repositioning its size box. 
Usage: Size a window. 


size box 

An icon in the lower right corner of a window. Dragging this icon allows 
the user to alter the size of the window by repositioning the lower right 
corner. 


socket 

A connector with holes. Try to use the specific socket name: the mouse 
socket, the external disk drive socket. 

See Also : connector 


software 

A general term for programs or programs. Be specific where possible. Use 
"application software", "system software", "accounting software", or 
better yet, the specific program name. 


space bar 

The long, unlabeled bar on the Macintosh keyboard. Pressing the space bar 
while typing puts a space at the insertion point. 
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space character 


Not blanle or blank character. Acceptable to use "space" on subsequent 
references. 

Usage: Press the space bar to get a space character. 


split bar 

Small black bars that may appear at either end of a scroll bar. Dragging 
a split bar into the window and releasing the mouse button causes the 
window to be split in two panes. 

See Also: split a window, pane, window 

split (a window) 

Dragging a split bar into a window to divide it into two or more panes. 
See Also: split bar, pane, window 


start up 

To switch on a Macintosh with a program disk in the disk drive causing the 
Desktop Manager to present itself to the user. 


suspend 

To stop a process in such a way that it can be resumed later. 


switch on 

To turn on the Macintosh on/off switch. 


symbol 

Don't use; use character, letter, number, or icon. 


system 

Broad term that includes the Macintosh, its accessories, and its software. 
Usage: Instead of system, use the most specific term possible. 


system software 

Not systems software. Consists of the basic resources and capabilities of 
Macintosh. Macintosh system software includes the operating system, the 
device drivers, the Desktop Manager, and the Toolbox. 



A key on -the Macintosh keyboard that in certain programs simulates the 
functions of its typewriter counterpart. Note capitalization. 


text 

Information represented in characters . 


title bar 

The horizontal bar at the top of a window containing the name of the file 
from which the document was taken. Title bars may have a close box. 

See Also: window, file, document 


turn on 

Don’t use; use start up or switch on. 


type 

To press and release one or more character keys on the keyboard or numeric 
keypad. 

See Also: press 

Usage: Type the following. Type on the keyboard. 


typeface 

A collection of letters, numbers, punctuation marks, and other 
typographical symbols with a coherent "feel” and consistent design. 
Typefaces have distinct names like Helvetica, Cream, and Bocklin. 
See Also: type style, font 


type style 

A stylistic variation applied to a typeface; examples are boldface, 
italic, underline, shadow, and outline. 


user 

The person operating or controlling a computer system. The person reading 
your manual. Using the second person usually eliminates the need for this 
word. If you are writing for programmers who are programming for users, 
then use this term to refer to their users. 
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user interface 


The rule^ and conventions by which a computer system communicates with the 
human user. Avoid this term. 


video monitor 

Don 1 1 use; use M Macintosh screen". 


window 

A presenter of information on the Macintosh screen. A window appears on 
the desktop. 

See Also: desktop, document, program, active, inactive window 

Usage: Open, close, size, or drag a window. Bring a window to the front. 


word wraparound 

The phenomena in text editing where words that are too long for the 
current line of typing automatically jump to the beginning of the next 
line without using the Return or Enter keys. 


write 

To transfer information from the computer to a destination external to the 
computer, such as a disk drive, printer, or modem. 

Usage: Use write only to explain the physical phenomena. 

Otherwise, use save. 
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MACWR ITS 


See Also: Macintosh Owner's Guide 


Modification History: Pre-alpha draft L. Johnson 7-18-83 
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ABSTRACT 

The manual assumes a basic knowledge of the Macintosh — how to use the 
mouse, pull down menus, select, choose, etc* 

Learning MacWrite is a tutorial for the naive user* It teaches basic 
MacWrite word processing skills. 

Applying MacWrite is a quick reference for basic MacWriter operations 
and a source for procedures to do more complicated tasks. 

The Reference chapter describes the features of the application. This 
chapter is not ready now and will be sent to you within a few days. 


Comments : 

There are more "recipes'* that can be added to the cookbook and introductory 
text will get more attention. 
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Learning MacWrite 



Introduction 


This tutorial has two parts. The first part is designed to get you 
started using MacWrite. You* 11 be introduced to MacWrite *s special typing 
features, then you 1 11 learn how to do some editing, first changing format 
by resetting margins, tabs, line spacing, and text alignment, and then 
changing the look of some of what you typed. 

In the second part of the tutorial, you *11 learn to edit both text and 
format in more detail by changing a memo that’s already stored on the 
disk. 

When you finish the tutorial and begin to create your own documents, you 
may still need some assistance or reminders: refer to Chapter 2, Applying 
MacWrite, for quick procedural summaries of the tasks you can do with 
MacWrite . 

The Macintosh Owner’s Guide orients you to the Macintosh, and it teaches 
you the basic mouse techniques you’ll need in order to use all Macintosh 
applications. Although mouse techniques will be covered briefly the first 
time you do them in the tutorial, you should already know how to: 

- Click: to select places and actions 

- Drag: to select text and move things around 

- Choose from a menu: to choose commands from the menus in the menu 
bar. 
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CREATING A DOCUMENT 
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Getting Started 




<<temporary finder instructions for loading MacWrite>> First, get MacWrite 
from the Desktop Manager. 


Insert the Sony disk, metal end first, into the disk drive* 


Click the MacStuff icon to select it. 

To click: Position the pointer on something — the MacStuff 
icon, in this case — and quickly press and release the mouse 
button . 


Choose Open from the Pile menu. 

To choose from a menu: Position the pointer on the menu 
title — File, in this case — and drag to the command you want. 





Figure 1 Choose from a Menu 


Click OK on the clock 

<<The MacStuff window is open and you can see icons 
representing what’s stored on the disk you inserted. >> 


Click the MacWrite «MacAuthor» icon to select it. 
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Choose Open fron the File menu* 



Figure 2 Seleting the MacWrite Application 


The desktop clears, except for the menu bar, and an hourglass that tells 
you to wait a bit while the Macintosh gets MacWrite to the desktop. 

The MacWrite window appears over a nearly empty document. A MacWrite 
window has all of the elements of Macintosh windows , the title bar , scrol 
bar and size box* Inside the window, there are two items that are part of 
the "empty" document, a ruler and a blinking vertical bar. (If the word 
window still brings to mind glass, buckets and squeegees, you really need 
to read the Owner’s Guide and get to know electronic windows. They open 
like a charm and don't need cleaning.) 
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Figure 3 shows you a new document window in HacWrite. You'll learn how 
to use most of what you see as you read the tutorial. 

The oenu bar contains lists of commands. 

The title bar names your document and lets you move the document 
window. 

There's a ruler with settings that you can change for margins, 
tabs, line spacing and text alignment. 

The blinking, vertical bar marks the spot where text is typed. 

That spot is called the insertion point. 

The scroll bar allows you to move a long document up or down in 
the window so you can see all of it. 

The size box allows you to change the size of the window. 







Figure "3 


A Document Window 






Typing Text 


You might not use the term ’’document" to describe what you’re going to 
type in the next few minutes. But to MacWrite, a document is what you 
create when you put anything in a document window, whether it’s one word, 
a laundry list, a legal brief, or even a graphic design taken from 
MacPaint . 

Typing with MacWrite is similar to typing on a typewriter, with a. few 
(notable ) exceptions . 

- Every character you type is added to your document at the spot, 
called the insertion point, marked by a blinking vertical bar that 
moves as you type. 

- The Backspace key moves the insertion point backward, removing what 
it backs over. 

- The Return key moves the insertion point down to the beginning of the 
next line. 

- You don't use the Return key to move to the next line when you come 
to the margin. MacWrite does it for you automatically with a feature 
called word wraparound. 

The Insertion Point 

Type this sentence. 

A penny earned isn't much. 


Notice that the insertion point moves along with the typing, marking the 
spot where the next character appears. 
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Figure 4 Typing 


Backspace to Delete 

Press the Backspace key until the insertion point is back to 
the beginning of the line. 

<<Picture of keyboard>> 

Your typing disappears. 
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The Return Key 


Type the following list (or any other four-item list 
currently on your mind), and use the Return key to move to 
the next line* 

If you make a mistake, just backspace and retype. 

Barbecue sauce 

Ribs 

Corn 

Dinner 

Notice that the insertion point moves down to the beginning of the next 
line when you press return. 


Press Return twice after the last entry in your list to skip 
a line* 


You f ve just used return to move the insertion point to the next line. 
Next, you'll see that when you come to the right margin, you keep typing 
and MacWrite moves the insertion point automatically to the beginning o£ 
the next line . 

Word Wraparound 

Now, type the following sentence and don't use the Return key. 
(Vegetarians may make appropriate substitutions.) 

I love barbequed ribs smothered in sauce and served with fresh corn 
on the cob covered with butter. 
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Figure 5 Word Wraparound 


Only use the Return key when you’re typing lists, ending paragraphs, 
skipping a line; in other words, only use it when you want to move down a 
line before you get to the margin. 


[ Word wraparound is more than just a convenient feature to speed typing. 
It’s a primary element in determining how MacWrite readjusts spacing in 
paragraphs when you’ve changed something, added a word, deleted a 
sentence, changed the margins. In other words, MacWrite uses it to make 
the changes you want. So give Macwrite a break — let it wrap words when it 
wants to. You use Return only to stop MacWrite from wrapping words, when 
you want to start another line before you’ve come to the margin. 

A word of reassurance: It’s not fatal if you use Return at the right 
margin. You’ll learn how to recover from an unwanted Return. It just 
takes you and MacWrite a little longer to do some editing tasks. ] 

Caps Lock Keys 

The Caps lock key capitalizes letters and is convenient to use when you 
want to capitalize a word or more. With Caps lock engaged, you still use 
the Shift key to type the upper symbols on keys, like the question mark 
(?). And you still use the Shift key for capitalizing when you don't need 
the convenience of Caps Lock. 
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Press Return twice to skip a line. 




Press the Caps Lock key. It will stay down until you press 
it again. 


Type your name, and with the Shift key put an exclamation 
point (!) after it. 

Press Caps Lock again to disengage it. 

If what you see doesn’t match what’s on the screen, don’t worry about it. 
The point is to get some practice using the keyboard and the special 
Macwrite typing features. However, if you don’t like what’s up there (you 
loath ribs, perhaps), you can undo everything you just did using a 
MacWrite miracle called the Undo command. 

Here’s how it works. 




Choose Undo from the Edit menu. 

Remember how to choose from a menu? Postion the pointer on 
the menu title and drag down and release the mouse button on 
the command you want. 
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Figure 6 Choosing Undo 
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It's gone. All of It. Undo undoes your last keyboard or mouse action, 
and your last action was typing. Undo doesn't just undo the last thing 
you typed, it undoes typing. 

But that's not all. 

You can get your typing back by undoing the Undo, now named Redo. 


Choose Redo Typing from the Edit menu* 

It's back. You'll get to know and appreciate the Undo command (and its 
alternate, Redo) as you work with MacWrite. 

That's all there is to typing text. 


[ You've been introduced to all MacWrite 's special typing features, except 
the tab key. You'll learn something about tabs in the next exercise, and 
more in the second part of the tutorial. 

You've just created a document, not a particularly important one, but a 
document nevertheless. Next you'll be introduced to the ruler and how to 
use it to set text format. ] 
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Changing the Format 


Setting the format of text means determining the arrangement of text on 
the page. It's setting the margins, tabs, line spacing, and text 
alignment at the margin. 

With MacWrite, you use rulers to set the format. MacWrite gives you the 
first ruler with a preset format at the top of a new document. You can 
leave this format as it is or change it. 


. Left margin marker 


• indent marker 


I \^J / Single spacing box active 

I / / , 1 1/2 spacing box J 

/ / / / j Double spacing box/ 

g/F ol^fer Edit Seqry Fofnwt /Style Fonts ^eclol 


f T ab markar 
at 5 1/2 
Inches 

Right margin 
at 7 1/2 
inches 


> Decimal tab wen 
Regular tab well 


'Left margin at 1 1/8 inches 


Active I I 
left aligned box I 

Center aligned box 


Right aligned box 


Full justification box 


Figure 7 The Preset Ruler 
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The ruler you see is a shortened view of the 8 1/2 inch ruler MacWrite 
uses to match the width of a standard page. You'll always work within at 
least a one inch left margin that appears when you print. You can widen 
your work area on the right by maneuvering the window to expand your view 
to 8 1/8 inches. In fact, if ever you can't find the right margin marker, 
its over between the 7 3/4 and 8 1/8 inch • <<include metric measurement)^ 

Here are some basics about rulers : 

- You can change the format by changing any or all of the setting on 
the ruler. 

- The change affects all the text between that ruler and the next. 
(Right now, there's only one ruler so it affects the entire 
document . ) 

“ You set the overall format for your document on the first ruler and 
then vary it by inserting other rulers using the Format menu. 

Now, you'll change settings on the ruler and see how these changes affect 
your text. Later you'll learn how to insert rulers to vary the format in 
different parts of your document — to create formats for tables, indented 
text, or centered titles, for instance. 

Changing Margins 


Drag the right margin marker to the 6 1/2 inch mark on the 
ruler. 

To drag a marker: Position the pointer on the marker; press 
the mouse button and while pressing, move the mouse (and the 
pointer) to the new location (in this case, 6 1/2 inches); 
release the mouse button. 
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Figure 8 Changing the Right Margin 


Try to drag the right marker over past the tab toward the 
middle of the ruler • 

Foiled! You can't move a margin marker past a tab. 


Drag the right margin hack to the 6 1/2 inch marker. 

Notice in Figure 7 that the left margin looks different than 
the right. It's actually two markers stacked together the 
left margin marker and the indent marker. When you want to 
change the left margin of a document, you'll move both of 
these, one at a time, ^^illustration and pictured 
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at 7 1/2 
inchtc 



Figure 9 The Left Margin and the Indent Marker 

First, position the pointer on the stack and drag either 
marker over to the 2 1/2 inch mark* 

It'll usually be the indent marker that you drag from the 
stack, but if you carefully position the pointer on the 
bottom angles of the triangle, you can drag it first from 
the stack. It takes a little practice. 


Now, restack the two under the 2 1/2 inch mark by dragging 
the other marker over* 
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Figure 10 Changing the Left Margin 


[ Let’s digress a bit and take a look at these two markers* 

The indent marker only affects the first line of a paragraph 
and any line that you’ve ended by using the Return key, like 
the list you typed* 

If the indent marker is moved to the outside of theleft 
margin marker, the first line of paragraphs (and lists) move 
to the outside of the left margin marker* Use it this way 
to make bulleted paragraphs* 

If the indent marker is moved to the inside of the left 
margin marker, the first line of paragraph (and lists) moves 
to the inside of the left margin marker. Try it if you 
like, but be sure to restack the markers under the 2 1/2 
inch mark* ] 

If your document doesn’t look like the one below, don’t worry* The 
important thing is to move the margin markers and see the changes they 
make • 

Changing Line Spacing 


Line spacing is controlled by the three boxes near the center of the 
ruler* 
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Figure 11 Line Spacing Boxes 

Choose the 1 1/2 space box by positioning the pointer on it 
and clicking the mouse button* 

Everything you typed now appears in 1 1/2 spacing. 


Click the double space box* 


Now everything is double spaced. 
Using the Scroll Bar 


If you've been typing what we've given you to type, or improvising with 
approximately the same number of lines, you just saw the bottom of your 
document move out of view. To move it back into view, you scroll the 
document down using the scroll bar. 


Click the down arrow at the bottom of the scroll bar until 
you can see your name* (The top of the ruler disappears*) 
Click the up arrow until you can see the line spacing boxes 
on the ruler. 

<<CALL OUTS: scroll bar, scroll box, gray area, up arrow, 
down arrow , ) 
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Figure 12 The Scroll Bar 


The scroll box moves as you scroll, showing you approximately where you 
are in your document. 


[ Look in your Owner* s Guide tutorial if scrolling is completely new to 
you, or for a review of all scrolling techniques, look in Applying 
MacWrite, Chapter 2. ] 

Press the UP arrow until you see the top of the ruler. 

Click the single space box so you can see the whole ^ 

document • 

Changing Alignment 

Next, change how text aligns at the margins. Use the four boxes on the 
bottom right of the ruler. 
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Figure 13 Changing Alignment 

<<CALL OUT - left align, center align, right align, fully justified>> 

Center your words between the margins by clicking the center 
alignment box. 


Next, click the next box to the right, the right alignment 
box. 
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Figure 14 Right Align Text 
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As you can see, everything lines up at the right margin, with a ragged 

left margin* You f 11 think of some uses for this, poetry perhaps. ^ 

In fact, remember the Undo command? Use it to retract your last action, 
and return to centered text. 


Choose Undo from the Edit menu. 


Undo undoes typing, as you saw earlier, and changes you make to ruler 
settings and most commands from the menu (redo undoes Undo). Just keep in 
mind that you can only retract an action if you choose Undo before you do 
anything else. 


Now, click the last box to have text evenly spaced and 
aligned to both margins: this is called full justification. 





Figure 15 Full Justification 

Text is fully justified except where you’ve used the Return key. If you 
can't see the difference, click back and forth between the left aligned 
box and full justification. 

Remember when you learned word wraparound? MacWrite wraps the word around 
without returns just so this kind of spacing can happen when you justify 
text. You'll see the significance of word wraparound again when you learn 
more editing in the second part of the tutorial. 
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There are two more items on the ruler to be introduced — tab markers and 
the tab wells, but first, learn to save your work and take a break if 
you ? d like. 
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Saving Your Work 


Every 20 minutes or so you should stop what you’re working on and save 
your work. Rarely (but once is enough) you’ll lose your work on the 
screen because of a power failure or computer malfunction* If you save 
your work onto a disk, you’ll always have a recent version to use as a 
backup* The Owner’s Guide thoroughly covers saving documents, so you’ll 
just get a summary of the procedure for Macwrite here* 


Choose Save from the Folder menu* 


A box appears asking you for more information, in this case, the name you 
want to give this document. Notice that Do It is gray, denoting that 
that’s an inoperative button for this part of the procedure. 


Type your name as the name for this document, although you 
could name it anything. 


As soon as you start typing, the OK <<do it>> button is operative. In 
MacWrite , all commands that you can’t or shouldn’t use at a given time in 
a procedure are in gray. 


Click the OK button «Do It» 

A second or two later, the Save box disappears and you can 
work in your document again. <<dialog box and alert box 
lexicon is still pending>> 

Just leave everything as it is and come right back. If 
something should happen to your document , you have a copy of 
it on the disk. 


Using Tabs 


Ready to start again? MacWrite has two kinds of tabs, regular and decimal 
tabs. You get regular tab markers from the first tab well, and decimal 
tab markers from the second one. 
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Figure 16 Tabs and Tab Wells 

Regular tabs perform the same function as tabs on a typewriter: to indent 
the first line of a paragraph (although you f 11 also use the indent marker 
to dc this); and to set up columns aligned at the tab marker. 

Decimal tab markers line up columns of numbers (or words, too) at the 
decimal point position. 

Try setting a decimal tab, and then use it and the regular tab to see how 
they work. 


Drag the scroll box to the top of the scroll bar to see the 
ruler. 


Drag a decimal tab to the 4 1/2 inch mark. 

To drag a tab from a tab well: Position the pointer on the 
tab well. Press and hold the mouse button and drag the 
pointer (and an outline of a tab) up to the number scale of 
the ruler. 


[ By the way, you don't have to be too careful dragging tabs 
and margin markers. Once you position the pointer and 
press, MacWrite's only interested in where you release the 
mouse button. You can take a direct route there or meander 
around the desktop first. This is true when you drag the 
scroll box as well. ] 


The insertion point is at the bottom of your document, where you last 
typed text. You're going to add text to your list at the top of the 
document at the tab stops you just marked on the ruler. Since you can 
only add text at the insertion point, you'll need to move it up to the top 
of the list. Here's how you move an insertion point, called selecting an 
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insertion point. 


On the first line of the list, select an insertion point 
after the word sauce by positioning the pointer anywhere on 
the line and then clicking the mouse button. 

Because there’s empty space after the text in this list, you can click 
anywhere in the space and the insertion point will appear right after the 
last character you typed. 

Press the Tab key. 

Watch the insertion point move to a position under the 
decimal tab marker. When you press the Tab key you are 
creating a tab stop where you’ve placed the tab marker. 

Type the amount, ”$33” • 

The numbers move to the left, aligned at the right. 

Suppose you make a typing error while you’re typing at a tab 
stop. You’ll use the Backspace key to remove text just as 
you’ve been doing. But if you backspace after you’ve 
removed the last character, you’ll remove the tab stop and 
move the insertion point back to the end of the word, sauce. 

In fact, try it and see what happens. 


Press Backspace four times, three to remove $33 and one more 
to remove the tab stop. 

The insertion point is back to the word, sauce. 


Press Tab and retype ,f $33 M . 

Press Tab again. 

The insertion point moves to the next tab stop on line. 


Type, Amy 

Characters move the right at regular tab stops just as you’d expect. 

[ When you press tab, MacWrite moves the insertion point to the first tab 
stop it finds, decimal or regular, and then when you press Tab again, it 
looks for the next one on the same line, or if there isn’t one, moves down 
to the first tab position on the next one. ] 





Select an insertion point after the word ribs on the next 
line. 

Press Tab 

Type the amount ,, $77.98 H 

The digits to the left of the decimal point move to the left, and those to 
the right, move to the right. 

Press Tab again. 




Type The End 



Figure 17 Using Tabs 

To practice, go ahead and insert tabbed text on the next two lines if you 
wish. Then go on to the next part and so some editing. Or go on now if 
you like. You’ll work with tabs again in the next section of the 
tutorial. 
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Editing Text 




Editing text means to change it in some way. In- this section, you’ll do 
an editing tasks that’s typical of the way you. do ail editing on MacWrite: 
first make a selection and then use a command to act on the selection.. 

Changing Text Style 

The text you type can be put into several different styles and type sizes. 
A text style is a variation of a typeface, making it bold, italic, 
underlined, etc. Here's how you change text style: 


- You select what you want to change and then choose the new text style 
from the Style menu 

- The command, Plain Text, is the normal style for text until you ^ 

change it; choosing it will remove all the other styles from the 
selection. 


Select the word "love” by dragging • 

To select by dragging: Position the pointer in front of the text to be 
selected; press and hold the mouse button and move the mouse, dragging the 
pointer across the text; release the mouse button when the text you want 
is highlighted. 


Your selection is highlighted on the screen. Now, do something to it by 
choosing a command from the Style menu. 


Choose Underline from the Style menu* Notice that Plain 
Text is checked in the menu as the current style for the 
word love. 




"Love" is now underlined and still selected. In the style menu, Underline 
is checked. 

Since all the styles can be used in combination, go ahead 
and choose all of them, one at a time. While you're at it, 
choose 24 point type, too. 
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Figure 18 Changing Text Style 

"Love" is bold, underlined, outlined, shadowed, italic and in 24 point 
type, and all these styles and the type size are checked in the Style 
menu. It's still selected and will stay selected until you select 
something else. 

Select an insertion point after your name: position the 
pointer anywhere after the end of the text and click the 
mouse button. 


The insertion point appears after the last character (or Return) of the 
text you typed. 

[ The insertion point i£ a selection. Think of it as a selected spot on 
the screen that you do something to. You type there. When you're 
choosing type styles for a word, you may want to deselect the word to see 
it better by selecting an insertion point any where in the text. ] 

Needless to say, type styles and sizes can add emphasis and interest to 
text, if used with discretion. 


Put "love" back to the Plain Text: select it again, and 
choose Plain Text from the style menu. 

There is more to learn about text style. What happens if you type text 
after the word "love." What style is it in? How do you remove one style 
while keeping another? These are the kinds of questions that you take to 
Chapter xx, Applying Macwrite. More procedures and details you need to 
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know to work with MacWrite are there* 


Quitting Macwrite 


Another break? You* 11 quit Macwrite and return to the Desktop Manager 
where you can eject the disk and take leave of Macintosh or continue with 
the second part of the tutorial. 

First, decide if you want this treasure you’ve just created. If you do, 
save it before you quit. 


Choose Save from the File menu. 

The Save box appears with the n 
you’ve named a document, it’s n 
save it. If you want to save i 
just start typing a new name, 
the old version under the old n 
version under the new name. 


name of your document. Once 
name appears each time you 
it under a different name, you 
You’ll end up with a copy of 
name and a copy of the current 


Click OK «D0 IT» 


Choose Quit from the File menu. 


The Desktop Manager appears. 


Now you can eject 
right — trash, for 


the disk <<by clicking one of the icons on the 
instance — and choosing Eject from the File menu.>> 
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EDITING A MEMO 


Editing means changing the text or format of a document. It can be 
anything from correcting a few typos to drastically altering both content 
and format. Most text editing with MacWriter involves selecting text and 
choosing the appropriate command from a menu as you did when you changed 
the text style. Format changes involve using rulers as well as using the 
Format menu. 

On the following page is a hand-corrected copy of the memo that you re 
about to put on your "desktop • " You* re going to learn to edit with 
MacWrite by making the indicated changes. Read the memo and note the. 
changes and then read how to get this document from the disk to MacWriter 
using the Desktop manager. 
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Date: July 16, 1983 
To: Robert 

From: Mildred 

Re: Finance Meeting Agenda' 


dert/fiT 


Here are my comments on your proposed agenda for the Finance 
group meeting jiext vest 

L Movin$^Discussing the moving date seems premature and will 
bog us down in spoliation slice there are so many untowns. Let’s 
wait awhile. 

* 1 T e chnical - Presentation: Fm concerned about John giving the 

technical presentation llrTilrm nut Intrlj. and I really thini Frank 
v, has a better handle on the current status of manufacturing 
£ developments. See what you can da 

^ 3. Party: A oeftttfgefitliparty for Finance sounds great Since 
^ there won’t be much discussion, leave it off the agenda. Call Tim to 
help set it up^gv^ 



C A130, keep the costs dow n? 

The rest of the agenda is fine. As always, in the interest of brevity, 
keep Joe from straying off the subject You can reach me as follows if 
you have questions: ^ 

New York Tlu J and L 

Washington '7/iy' \ Emery’s 

Cleveland V^-T^l Mother's 
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Getting an Existing 
Document 


If you ejected the disk, insert it into the disk drive* 


Click OK on the clock* 


You’re back to the Desktop Manager and the window is open onto your disk 
contents. Look for a document named MEMO in the MacStuff disk. 


Click the MacWriter icon named. Memo. 

Choose Open from the File menu* 
or 

Double click the icon to open its window* 

Remember this shorcut from the Owner's Guide? Position the 
pointer on the icon and quickly press and release the mouse 
button twice. 
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Editing Text 




Editing can involve changing both text and format. You’ll do both to this 
memo. You’ll start with text editing since most of the commands in the 
menu bar help you edit text. 

Inserting Text 


In the first part of the tutorial, you selected an insertion point at the 
end of your typing after you finished changing text style. You can select 
an insertion point within a word to insert a letter, within a sentence to 
insert words, at the beginning or end of a line to insert a line (using 
the Return key); in other words, you can insert any keyboard character or 
group of characters at the spot where you’ve selected the insertion point. 


At the beginning of the paragraph that starts with "Moving" 
select an insertion point by clicking in the space between 
’•Moving" and the colon ( : ) • 

Remember, to select an insertion point, position the pointer and click the 
mouse button. 


Press the space bar to Insert a space and type the word 
"Date." 


Text shifts and realigns to accommodate the new text. 


[ The space bar inserts a character into your document just as keys do. 
You don’t see it, but like any character, you’ll telling MacWrite to 
insert something into your document, in this case, a space between 
letters. ] 
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Removing Text 




You'll learn a couple ways to remove text* The first, cutting, is the 
faster and safer* This method saves the cut text so you can retrieve it 
later and put it back in your document , where you cut it or someplace 
else* 


Scroll to the next windowful by clicking the gray area below 
the scroll box* 


Select the text "mental health” by dragging* (See Fig* n*) 


Remember, to drag, you position the pointer just in front of the word ^ 0 ^ 

"mental." Press the mouse button and drag to the end of the word 

"health". 

The selection is highlighted, ready for the next action. 


Choose Cut from the Edit menu* 
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Figure 18 Cutting Text 


[ The text disappears. Notice how the paragraph has 
readjusted to account for the missing words. This is word 
wraparound at work again. Think of word wraparound as 
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creating a continuous line of type that's stopped when you 
use the Return key. So when you add or delete text from 
this line, MacWrite easily readjusts the spacing between 
returns. 

The text you cut is placed in a special document , the 
clipboard, from which it can be retrieved. You* 11 get a 
thorough explanation of the clipboard a little later in the 
tutorial. 

Replacing Text 

Look at the next editing task marked on the memo. You're going to replace 
"technical" with "manufacturing." Although you can use what you just 
learned to cut "technical" and then insert "manufacturing", there's a 
faster way to replace text: simply select it and type its replacement. 

Since replacing lets you do some fast editing, how about doing some fast 
selecting by double-clicking, the same shortcut you learned to open icons 
from the Desktop Manager. 


Double-click to select the word "Technical" at the beginning 
of the paragraph. 


Double clicking is a quick way to select a word. 


Type "Manufacturing." 

"Technical" disappears and "Manufacturing" takes its place. Notice that 
you can replace text of one length with longer or shorter text and 
MacWrite makes the adjustment in spacing within the paragraph. 


Another Way 
to Remove Text 


Now, delete part of a sentence in this same paragraph with a second method 
for removing text. Just select it and Backspace. When you do, you'll 
notice that the paragraph spacing doesn't readjust as it has been. You'll 
see why in a minute. 


Select "He's been out lately and". 


Press Backspace once. 


Be warned. Text removed by this method can be retrieved only if you 
immediately choose Undo from the Edit menu. Text is only saved on the 
Clipboard for later use when you remove it with Cut from the Edit menu. 
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Coping with 
Unwanted Returns 


What about the paragraph readjustment? Nothing's wrong; Return was used 
at the end of the line (on purpose to show you the effect) and it's 
stopping word wraparound from readjusting the spacing. Here's how to 
recover from an unwanted Return. 


Select an insertion point at the beginning of the next line: 
it starts with "Frank 


Press Backspace once* 


That's how you get rid on any unwanted Returns and get word wraparound 
working again: select an insertion point at the begining of the next line 
and Backspce once. It's easy. But it's easier to let MacWrite wrap words 
in the first place. 

Next, you'll be introduced to the Clipboard and how to move text. 

The Clipboard 

When you do choose Cut from the Edit menu to remove selected text, 
MacWriter places the text on the Clipboard. 

First, take a look at it. 


Choose Clipboard from the Folder menu* 


The clipboard window appears in front on the desktop. Notice that the 
last text you cut it there. 

[ You can change the size of this window, move it around, and put it's 
contents back into your document: you just can't edit the text. In fact, 
that's how you move or copy text, you put it in the Clipboard, and then 
you paste it back into your document. ] 
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Figure 20 The Clipboard <<clippings» 


Now you have two choices : you can keep the Clipboard on the desktop by 
activating the document window, placing it in front and the Clipboard 
behind; or, you can remove the clipboard from the desktop completely by 
choosing Hide Clipboard from the Folder menu* For now, put the Clipboard 
behind the memo document by activating the memo document window* 


Click anywhere in the blank part of the memo window* 

If windows still confuse you, look them up in the Owner's Guide or read a 
brief discussion of them in Chapter x. 

Moving Text in 
Your Document 


You move text by selecting and cutting it from one place and pasting it 
into another. 


Select "Also, keep the costs down*" by dragging* Be 
careful not to select the rest of the line* 


Choose Cut from the Edit menu* 


Select an insertion point right after the last period in the 
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paragraph just above 


Choose Paste from the Edit menu* 

You pasted this paragraph right at the end of the above 
paragraph and not at the beginning of the next line, 
although it would have looked the same. You moved a line to 
the end of a paragraph that ended with Return. Had you 
moved it to the beginning of the next line, and then edited 
the line above, word wraparound would not have worked. 

You’ve got too many lines between paragraphs. Here’s one 
way to cut blank lines (or any lines) from a document. 


Select an insertion point at the beginning of the (blank) 
line just above the paragraph that starts with "The 11 . 


Press Backspace twice* 

Remember, the other way to remove lines (or anything else 
that you can select in the document): drag to select two 
lines and choose Cut from the Edit menu. That way you save 
the blank lines. 


Copying text works like Cutting it, except you keep the 
orginal in the document. You select what you want to copy. 
Choose Copy from the Edit menu, select an insertion point 
and choose Paste from the Edit menu. 
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Editing Format 


Centering 


You've just learned to edit text with MacWriter. Earlier, you learned to 
alter the format of a document by changing settings on a ruler. 

To change the format of part of the memo, you'll use the Format menu to 
insert rulers and then change the settings on a ruler. You could easily 
end up with several rulers in a document, one for the main body, a 
different one for indented material, another for tables, etc. 

Now, you'll make the format changes that are marked on the practice memo. 
As you learn how rulers behave, you'll be able to change a format quickly, 
either while you're entering text or later when you're editing it. 

Title 

First, you're going to center the subject of this memo by inserting a 
ruler and changing the text alignment. When you insert a ruler, you 
select an insertion point at the beginning of the line where you want the 
new format to begin. 


Scroll to the top of the document* 


Select an insertion point at the beginning of the line that 
starts with M Re: ,f 


Choose Insert Ruler from the Format menu* 
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Figure 21 Inserting a Ruler 


The ruler you see is a copy of the one above it. Whenever you insert a 
ruler, you get a copy of the ruler that is controlling the text at the 
insertion point: the nearest one above it. 

If you make a mistake when inserting a ruler, just choose Undo Insert 
Ruler in the Edit memo. 


On this ruler, click the center alignment button. 

The line is centered and, unfortunately, so is the rest of your memo. 
Scroll to see it if you want to. 

Select an insertion point at the beginning of the paragraph 
that starts with the word "Here.” 


Choose Insert Ruler from the Format menu. 

Once again you see a copy of the nearest ruler above the insertion point, 
the one you just changed. 
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Click the left alignment button. 


The body of your memo is back to the standard format on the first ruler. 
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Figure~22 Inserting and Changing Second Ruler 


Using the Indent Marke 

Next you 1 11 Indent Mildred's specific comments and align the paragraph 
body. This time* to avoid indenting the rest of the memo, you'll insert 
two rulers* one at the beginning of the first comment (number 1), and a 
second at the end of the last (number 4.) Then* you'll only change the 
margin settings on the first. 


Select an insertion point at the beginning of the paragraph 
starting with "1. Moving Dates". 


Choose Insert Ruler from the Format menu. 


You see a copy of the nearest preceding ruler# 


Scroll to see the end of the text to be indented by pressing 
the down arrow. 




Try to keep the ruler you just inserted in view. 


Select an insertion point at the beginning of the line of 
the last paragraph which starts with "The rest." 


Choose Insert Ruler from the Format menu* 

Again, you see a copy of the ruler. 

Scroll back to the ruler just above this one. 

Next, you’ll indent the text by moving the indent marker. 

Drag the indent marker over to the 2 inch mark* 

Now, watch the magic. 

Drag the left margin marker over to the 2 1/4 inch mark* 
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Figure 23 Creating Indented Paragraphs 
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There are the paragraphs, indented 1/2 inch from the main body of the memo 
and also aligned within the paragraph (designated by the left margin 
marker in the ruler). By inserting rulers around these numbered 
paragraphs, you've made sure that the regular margins are maintained for 
the rest of the memo. 


[ You put the indent marker to the inside of the left margin when you want 
to have the first line of paragraphs indented — a common format for 
letters, reports, etc. You put it to the outside of the left marker when 
you want numbered or bulleted paragraphs, and indent the body of the 
paragraph under the text (not the number). Next, use this feature and 
type some new text into the memo. ] 

Select an insertion point at the end of paragraph #3, after 
the period. 

Press Return twice. 

Type the following paragragh. Remember, continue typing at 
the margin: don't use Return until you end the paragraph. 

4. Theme: Punk's fine if it's strictly departmental. 

Somehow I can't see Mr. Perkins-Elliot in pomade and safety 
pins. By the way, our insurance doesn't cover slam dancing. 


You're using the left margin marker to align the body of your paragraph 
inside the indent marker. The words wrap around at this margin just as 
you would expect. When you press return, the insertion point moves to the 
indent margin so you can create a new paragraph. Remember, the indent 
marker only affects the first line of a paragraph, and for MacWrite, any 
line after a Return begins a paragraph. 


Using Tabs 




You need to insert some dates into Mildred's schedule. 


Drag a regular tab from the first tab well to the x inch 
mark. 


The last column moves over. MacWrite puts tabbed text in the first 
sequence of tabs it finds. When you insert a tab between two tabs, it 
moves the columns on the right over to be aligned under the first two 
tabs. Here's how you insert another column and move the other back where 
it belongs. 


Select an insertion point just after "New York." 
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Figure 24 Inserting Tabs 


Press Tab and type "7/17." 


Select an Insertion point just after "Washington" ; tab and 
type "7/18." 


Select an insertion point just after "Cleveland"; press Tab 
and type "7/19-7/23." 
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Hiding Rulers 


Too many rulers can obsure your view of a document. 


Choose Hide Rulers from the Format menu* 


The rulers are gone, and now you can see the memo as it will look when you 
print it. 

If you want to see the rulers again, choose Show Ruler from the Format 
menu. Hide and Show Ruler appear alternately in the menu depending on 
which one is relevant. 

Inserting a ruler brings all the rulers into view. 

[ Rulers can be copied, and, except for the first ruler, they can be 
deleted or moved. After you*ve gone to the trouble to set up a 
complicated table, you can move it and the ruler that's formatting it to a 
new location in your document. ] 
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Printing 


«look in Applying MacWriter, page xx for current printing instructions .» 
You've finished the tutorial. Perhaps you'd like to save this version of 
the memo. Remember, each time you save a document with the same name, you 
replace the last version. So to keep the original teaching memo on disk 
for someone else, change this version's name to create a separate document 
and save both. 


Choose Save from the Folder menu. 
Type a new name after Save What:. 
Click OK «DO IT». 

Choose Quit from the Folder menu. 
Click OK «Go Ahead». 
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What Do I Do Now 


Play around with MacWrite. Write a letter to a friend, or type a memo 
telling your boss what you've always wanted to say but didn't dare, or * 

write us at Apple telling us how much you like MacWrite and Macintosh. 

When you start using MacWrite, you'll probably have questions. How do you 
copy or move a ruler? How do you get a top and bottom margin for 
documents longer than a page? Look in Chapter 2, Applying MacWrite. 

There you'll find basic skills and procedures to do most tasks you'll want 
to do with MacWrite. 
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Applying Mac Write 
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INTRODUCTION 


If you’ve gone through the tutorial, you’re familiar with most elements of 
MacWrite word processing- But perhaps you’re not quite familiar enough to 
do everything that you’d like to do to create a document- This chapter 
presents the tasks covered in the tutorial, as well as others in 
self-contained units that you can refer to when you need help- Of course 
not everything can be covered here; the Reference chapter (Chapter 3) 
gives you a more thorough conceptual understanding of the elements of 
MacWrite and will further enhance your ability to use it. 

MacWrite tasks fall into three general categories: editing, formatting, 
and printing. This chapter has a similar arrangement with tasks presented 
within each category. 
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BASIC SKILLS 


Since Macintosh basic skills and techniques are thoroughly covered in your 
Macintosh Owner* s Guide, the review that follows is a short refresher* If 
you find it too brief, you do need to take the time to read the tutorial 
in your Owner’s Guide* 
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Summary of Mouse Techniques 




You’ll use the following four mouse techniques to do just about every 
other task found in this chapter: 

-Clicking » to select something or make it active. 

-Dragging , to select or move something 
-Pressing » to cause a continuous action 

-Double-clicking , a quick way to select or activate something. 


To Click 




Position the pointer on what you want to select or make active* 
Briefly press and release the mouse button* 

To Press 


Postion the pointer on something* 

Without moving the mouse, press and hold the mouse button* «ILLUSTRATE» 


[ The result of pressing is in effect as long as you hold down the mouse 
button. Pressing on the scroll arrows results in continuous scrolling. 
Pressing on a menu title pulls down the menu and keeps it down until you 
release the mouse button* ] 

To Drag 


Position the pointer on something* 

Press and hold down the mouse button, and move the mouse* 

Release the mouse button* 

[ In general, you can cancel a drag in process by moving the pointer back 
where it started. Cancel a drag through a menu by moving the pointer off 
the menu • ] 

To Double-Click 


Position the pointer on something* 


Press and release the mouse button twice in quick succession* 

«ILLUSTRATE» 
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Selecting 


When you do anything on Macintosh, you do it by selecting something. The 
following is a summary of techniques to 

- Select text 

- Select a word 

- Select large areas of text or the whole document 

- To extend or shorten a selection 

- Select a ruler 

- Select an insertion point 

With text selected, you can move, resize windows, and scroll. MacWrite 
scrolls automatically when you are selecting into the next (or previous) 
windowful . 

To Select a Word 


Double click the word* 

To double click: Position the pointer anywhere on the word and quickly 
press the mouse button twice. 

To Select Text 


Drag across text to select it* 

- Drag along a line in either direction to select characters (including 
spaces) on the line* 

- Drag up or down or on a diagonal to select more than one line of 
text. 

To drag: Position the pointer just before or just after the text to be 
selected, press and hold the mouse button, and move the pointer to the 
other end of the selection* Release the mouse button. The selected text 
is highlighted* 

If you drag beyond the bottom or top edge of the document window, the 
document scrolls as you continue to select text. 
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To Select Large Areas of Text 


Click an insertion point just before (or just after) the text you want to 
select* 

Use the scroll bar (if necessary) to move to the end of the text you want 
to select • 

Position the pointer on the last character of the selection* 

Hold down the Shift key and click the mouse button* 

To Extend or Shorten a Selection 


Once you have completed a selection by releasing the mouse button, you can 
change the amount selected, extending it or shortening it from the bottom 
of the selection. 

Hold down the Shift key. 

Position the pointer where you want to extend or shorten the selection and 
click the mouse button* 

If you position the pointer and click anywhere above the selection, you'll 
select text from the top of the selection up to the pointer and replace 
the original selection* 

To Select a Ruler 


Click anywhere on the number line of the ruler* 

Position the pointer anywhere on the number line of the ruler and quickly 
press and release the mouse button* 

To unselect the ruler, click an insertion point anywhere in the document. 
To Select an Insertion Point ' 

Click an insertion point* 

Position the pointer where you want to make an insertion and quickly press 
and release the mouse button. 
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Scrolling is a technique for moving your document up or down in the 
document window, allowing you to bring any part of the document into view. 

To Scroll Text One Line Up or Down 


Click the up or down arrow on the scroll bar- 

To Scroll Text Continuously Line by Line in Either Direction 

Press the appropriate arrow at the top or bottom of the scroll bar* 
To Scroll by the Windowful 

Click the grey area above or below the scroll box* 

To Scroll to the Previous Windowful of Text 


Click the grey area above the scroll box* 

To Go to the End or the Beginning of Your Document . 

Drag the scroll box to the bottom or the top of the scroll bar* 

To View Any Part of a Long Document 

Drag the scroll box to a place in the scroll bar that 1 s about equivalent 
to where the text is in the document* ^ 

Think of the whole scroll bar as graphically representing the length of 
your document. If you want to see the middle of your document, drag the 
elevator to the middle of the scroll bar. 
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Working with Windows 


The documents that you work on appear in windows. You can 

- Move windows 

- Change the size of windows 

- Activate a window 

- Close a window 

To Move a Window 

Position the pointer anywhere on the title bar. 

Drag to the new location. 

You* re dragging an outline of the document window to a new location; the 
window moves when you release the mouse button. 

To Change a Window's Size 

Position the pointer in the size box (in the lower right corner below the 
scroll bar). 

Drag the size box until the window is the desired size. 

Dragging horizontally changes the width; dragging vertically changes the 
height; dragging diagonally changes both. 

To Activate a Window 

Click anywhere inside or on the window (except a close box in the title 
bar, if applicable). 

To Close a Window 

Click the close box on the left of the title in the Title bar of a window. 

Only desk accessories have close boxes in MacWrite. 
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EDITING TASKS 


This section covers basic procedures for most editing operations* All 
editing on MacWrite involves the process of selecting something and acting 
upon it with either commands in the menu bar or from the keyboard* 


«art» 
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Inserting 




You can insert into already existing text as little as a single character 
(including tabs, spaces, and returns) up to several pages of text. The 
new text will conform to the format of the nearest preceding ruler. 

Inserting Text 






Select an insertion point. 

Type new text. 

The text to the right moves to accommodate the new text* 

The insertion point for a new document is at the top left corner of the 
window under the ruler. 

Inserting (blank) Lines in a Paragraph 

Select an insertion point at the beginning of the line where you want a 
new (blank) line. 

Press the Return key twice. 

Inserting Rulers 

Select an insertion point at the beginning of the line where you want to 
change the format. 

Choose Insert Ruler from the Folder menu. 
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Removing 




Using Cut from the Edit Menu 


Select text to be cut* 

Choose CUT from the Edit menu* 

MacWrite places anything removed with the Cut command on the Clipboard, 
where it remains until the next Cut (or Copy). 

Using the Backspace 


- Press the Backspace key to remove text to the left of the insertion 
point. 

- Select text to be deleted and press the Backspace key once. 

Choose Undo Typing from the Edit menu as your next action to restore text 
removed by these methods. 

Removing an Unwanted Return 

The Return key inserts a non-printing character that interrupts 
wordwraparound. Unintended Returns will affect how paragraph spacing 
readjusts after editing: text will not fill into the empty space in the 
affected line so part of it will be blank. «illustrate» 


Select an insertion point at the beginning of the line below the one 
affected by the unwanted return* 

Hit Backspace • 

Removing a Ruler __ 

You can delete all but the first ruler of a document. 

Select the ruler by clicking on the number scale* 

Choose Cut from the Edit menu* 
or 

Press backspace* 
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Replacing 


After replacing, you can restore the selection if your next action after 
typing is to choose Undo Typing from the Edit menu. MacWrite treats 
pressing backspace as typing; so if you replace the selection with typing 
that includes using Backspace, Undo will undo both and restore the 
selection. 

Select what' 8 to be replaced. 

Type new text. 

You can replace the selection with nothing (simply remove it), by pressing 
Backspace after you’ve selected the text. 
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Moving Text 


Text, rulers, and graphics can be moved. For instructions on moving 
rulers and graphics see the following: 

- Moving or Copying Text with a different format 

- Moving Graphics in MacWrite 

Select text to be moved. 

Choose Cut from the Edit menu 

Cut Text is placed on the Clipboard where it remains until the next Cut 
(or Copy). 

Click an insertion point where you want the selected text to be moved. 

You can perform other MacWrite operations between the Copy step and the 
next one as long as you don’t cut or copy something else. 

Choose Paste from the Edit menu. 

You can select another insertion point and paste again. 
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Copying Text 


Text, rulers and graphics can be copied. For instructions on copying 
rulers and graphics see the following: 

- Repeating a format 

- Moving or copying text with a different format 

- Moving Graphics in MacWrite 

Select the text to be duplicated* 

Choose Copy from the Edit menu* 

Copied text is placed on the Clipboad where it remains until the next Copy 
(or Cut). 

Select an insertion point where you want to copy the text* 

You can perform other MacWrite operations between the Copy step and the 
next one as long as you don’t cut or copy something else. 

Choose Paste from the Edit menu* 

You can select another insertion point and paste again* 
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Moving or Copying Text Between Documents 


When you want to move or copy text from one document to another in 
MacWrite, you’ll cut or copy the text to the Clipboard, get the other 
document , and paste the contents of the Clipboard at the point where you 
want the text moved or copied. 

Select the text you want to move* 

Choose Cut or Copy from the Edit menu* 

The text is placed on the Clipboard. 

«other steps are finder dependent» 

The combination of the contents of the Clipboard and the newly expanded 
document cannot be larger than the memory allows. This limitation can be 
a bit difficult to calculate in advance. An alert message will tell you 
if you are exceeding the memory capacity. Read the reference sections on 
The Folder for a better understanding of this important element of 
MacWrite. 
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Moving or Copying Text with a Different Format 




If the format of the text you want to move (or copy) is different from the 
one where you’ll be putting it, you'll move (or copy) a ruler with it to 
maintain the text’s format in the new location. 

Insert a ruler at the beginning of the text you want to move (or copy). 

Select the ruler and the text by starting to drag on the number scale of 
the ruler and dragging across the ruler and the text. 

Choose Copy (or Cut) from the Edit menu. 

Select an insertion point where you want the text to be copied or moved. 
Choose Paste from the Edit menu. 
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Finding Text 


Use the Find command in the Search menu to locate any series of 
characters — usually a word, phrase or number — that you want to change. 
You can also find a place in your document that you f d like to work on by 
searching for a word in or near that place. 

MacWrite will search for words without regard for capitalization and 
accompanying end punctuation. The search moves from the insertion point 
to the end of your document, wraps to the beginning, and returns to the 
insertion point. 

Choose Find from the Search menu. 

A box appears as shown below. <<illus trate>> 

Type the characters that you're looking for after FIND WHAT: 


The first occurrence of the text after the insertion point is highlighted. 

If MacWrite cannot find what you typed, a box will appear: <<screen 
shot>> 

Click OK to return to the Find box. 

Click Done to end the search and edit the highlighted text if you wish, 
or 

Click Find Next to find the next occurrence of the word. 



Finding and Replacing Text 


You can replace a series of characters — usually a word, phrase or 
number — by choosing the Change command in the Search menu to find what you 
want and replace it with something else. 

MacWrite will search for words without regard for capitalization and 
accompanying end punctuation. The search moves from the insertion point 
to the end of your document, wraps to the beginning, and returns to the 
insertion point. 

Choose Change from the Search menu. 

A box appears : 

«CALL OUTS»FIND WHAT: CHANGE TO: « Find Next// Change Then Find// 
Change// Change All// Done» 

Type the characters that you want to change after FIND WHAT: 

In this step and the next, use a space before and after any series of 
characters you want treated as a whole, like a word, number, etc. 

Type the new characters after Change To: 

You can eliminate a word throughout a document by leaving Change To: 
blank; MacWrite will simply replace the designated text with nothing. 

Macwrite finds the first instance of the text after the insertion point 
and highlights it. 

Click one the following: 

Find Next to find the next occurrence of the text without changing this 
one. 

Change then Find to change this one and find the next one. 

Change to change this one only (used with Find Next). 

Change All to change all occurrences of the text. 

Done to end the search. 

Except Change All, after you've ended the search, these commands can be 
retracted if your next action is choosing Undo from the Edit menu. 


Finding and Replacing Text 
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Changing the Style or Size of Text 


The Style menu gives you a choice of several styles and text sizes that 
vary a typeface* Sizes are used singly* Styles can be used singly or in 
combination. The instructions that follow use style/size to mean style 
and/or size. 

When you change style size, all new text you add at an insertion point in 
the space immediately following the changed text will appear in that style 
size. An insertion point selected elsewhere will be in the style and size 
of the text immediately preceding it. 

Select text that you want to change or select an insertion point to put 
new text in a different style/size * 

Choose a style/size from the Style menu. 

When you choose a style/size, a check appears next to it in the menu. The 
selected text changes and remains highlighted. Text typed at the 
insertion point selected above will be in this style/size. 

To Return to Normal 


Select text or an insertion point to be returned to normal* 

Choose Plain Text for style and 12 point for size from the Style Menu* 


To Remove a Text Style 




Although you add styles one at a time, you remove them by returning the 
selected text to normal, and selecting the ones back again that you want 
to keep. 

Select the text to be altered. 

Select Plain Text in the Style aenu. 

This removes all styles from the selected text. 

Choose styles (one at a time) that you wish to keep. 
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Changing the Typeface 


The Font menu gives you a choice of several typefaces for one character or 
an entire document. When you change typeface, ail new text you add in the 
space immediately following the changed text will appear in that typeface. 
Text added at an insertion point selected elsewhere will be in the 
typeface of the text immediately preceding it. 

Select text or an insertion point where you want to change the font. 

Choose a typeface from the Font Menu. 

A check will appear next to the font you have chosen. 

To Return to the Normal 


Select text to be returned to normal. 

Choose Times Roman from the Font menu. 

Times Roman is the preset typeface for a new document. Your documents 
will be in this typeface unless you change it. 


Moving Graphics from MacPaint to MacWrite 


You can create a picture in MacPaint and move it to MacWrite and although 
you can’t edit it, you can change it’s size and move it horizontally. 

<<First steps deal with getting a picture from MacPaint and loading 
MacWrite» 

Select an insertion point* 

Choose Paste from the Edit menu* 
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Moving Graphics in MacWrite 


You can move a graphic design to another place in your document or 
maneuver it in its current position. 

To Resize or Move a Design Horizontally 


You'll drag the small size boxes on a selection rectangle that appears as 
a border around the design when you click anywhere on the design. 

The square on the left moves the picture to the left, widening it, and to 
the right, shortening it. 

The square on the right moves the picture to the left, shortening it, and 
to the right, widening it. 

The square in the middle lenthens or shortens the picture vertically. 


Click anywhere on the design. 

Drag these squares to maneuver the picture until it is positioned where 
you want it. 

To Move a Design 

Select the design by clicking anywhere on the design. 

A border appears around it. 


Choose Cut from the Edit menu. 

Select an insertion point where you want the top of the design to be. 
Choose paste from the Edit menu. 
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Setting Format on a Ruler 


The following shows you how to change format settings on any ruler. All 
new or existing text between the ruler you change and the next (or the end 
of the document) will be affected by any of the changes made as described 
here . 

Insert a ruler where you want the change to take place, or choose Show 
Rulers from the menu and find the nearest preceding ruler. 

To Change Margins 


Drag the left margin/indent markers and the right margin marker over to 
the desired positon along the number scale of the ruler. 

To Set and Clear Tabs 


(Position the decimal tab marker where you want the decimal point to be.) 

To Move Tab Markers 

Drag the tab marker to a new location along the number scale of the ruler. 

To Add Tab Markers 

Drag a tab marker from one of the tab wells to the new location under the 
number scale on the ruler. 

To Clear Tabs 

Drag the tab marker down to the base line of the ruler. 

To Set Line Spacing • 

Click the appropriate line spacing box. 
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Figure n Line Spacing 
To Set Text Alignment at the Margin 


Click the appropriate one of these: «lllustrate» Call outs-left 
alignment box, center alignment box, right alignment box, full 
justification box* 


Figure n Alignment at the Margin 
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Changing the Format for New Text 


To change the format as you are typing text, just insert a ruler, change 
any of the format settings you want, and continue typing. 

Select an insertion point at the beginning of the line where you* 11 type 
the new text. 

Choose Insert Ruler from the Format menu. 

The ruler that's inserted is a copy of the nearest ruler above the 
insertion point, the one setting the format of this area of text. 

Change the settings of the new ruler. 

- Reset the margins. 

- Reset the tabs. 

- Add tabs • 

- Clear tabs. 

- Change text alignment at the margin. 

- Center text. 

Type the new text. 

You can reinstate the previous format by copying the appropriate ruler 
(see Repeating a Format). 
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Changing the Format for Exisitng Text 


To change the format for some text while preserving the format of text 
that follows it, insert two rulers, one on either side of the text to be 
changed, and change the format of only the first one. 

Select an insertion point at the beginning of the line where you want a 
new format* 

Choose Insert Ruler from the Format menu* 

The ruler that's inserted is a copy of the nearest ruler above the 
insertion point, the one setting the format of this area of text. 

Select an insertion point at the beginning of the line after the last line 
of text to be changed* 

Choose Insert Ruler from the Format menu* 

Change any of the format settings on the first ruler you inserted* 

~ Reset the margins* 

- Reset tabs* 

- Add tabs* 

- Clear tabs 

- Change the justification* 

- Center text* 



Repeating a Format 


If you have rulers in your document with formats that you want to use 
somewhere else (for example, a format for a special table you are 
repeating with different entries), just copy the ruler to the new 
location. 

the ruler you want to copy by clicking on the number line of the 


Copy from the Edit menu. 

an insertion point at the beginning of the line where you want to 
the ruler. 

Paste from the Edit menu. 

The ruler appears above the line with the insertion point. 

This ruler will now alter the format of all text between it and the next 
ruler. 




Select 

ruler. 

Choose 

Select 

repeat 


Choose 
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Creating and Changing Tables 


You create tables using the tab markers. On MacWrite, you can add or 
delete text between one tab marker and another without disturbing text at 
the next tab as long as your editing doesn’t affect the tab position 
itself. 

Put tabs (regular or decimal) along the number line of the ruler where you 
want the table v s columns to begin. 

If you want the table to have different margins than the main body of 
text, see Changing Format for existing text or new text in this chapter. 

Type in table text using the Tab key to move from one column to another. 

Edit text at the tab stop using the Edit menu. 

If you insert so much text that it runs into the next tab postition, text 
at that tab position will be bumbed forward to the next tab, on that line 
or the next. 

If you delete text and the tab position, text at the next tabs will move 
back. 


Inserting a Column in a Table 


Use the following procedure to insert a column between two existing 
columns or to add a column anywhere to a table, or list. 


Drag a new tab under the mark on the number scale of the ruler where you 
want a new column. 

The column aligned with the tab to the right moves under the new tab 
marker. 

Select an insertion point just after the first line of text of the column 
on the left. 

You can position the pointer anywhere in the space between these two 
columns and click. 

Press Tab. 

The insertion point moves to the new tab stop and the first line of the 
right column moves back to its former position. 

Type the first entry of the new column. 

Select an insertion point just to the right of text in the second line of 
the left-hand column; press Tab and type the second entry of the new 
column. 

For each line of the column , continue to select an insertion point just 
after the left-hand column; press Tab and type the next entry. 
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Creating Top and Bottom Margins (Headers and Footers ) 


Top and bottom margins are called headers and footers in MacWrite. You'll 
create them separately from the rest of your document. You can repeat 
text such as chapter titles in both margins throughout your document. 

Headers-The Top Margin 


Choose Show Headers from the Format menu. 

The header window appears and can be manipulated like any other window. 

Set the width of the top margin with one of the following methods: 

- Move the left margin/indent marker over slightly and put a tab where 
the left margin/ indent marker was. Press Tab up to 6 times to create 
a maximum of xx inches of space. 

- Click the double space box on the ruler and press Return once for a 
xx inch top margin 9 and twice for a xxinch margin 


MacWrite only allows you to use the Return key twice to create the top 
margin, so you'll need to use 1 1/2 or double spacing to achieve a margin 
wider than two lines, or use Tab keys like Returns to create lines. 

Select an insertion point and type the text that you want repeated in the 
top margin. 

The header may be edited like any other document. 

Position the pagination symbol where you want page numbers to appear. 
Position the clock icon and/or date icon where you want these to appear. 
Activate the document window. 

The header is inserted into the document at the top of each page. The 
header window moves behind the document window, remaining barely visible 
at the bottom of the desktop unless you have moved it. 

If you choose Hide Header, the header window disappears from the desktop 
and the header disappears from your document. 

Footers-The Bottom Margin 


Choose Show Footer from the Format menu. 

The footer window appears and can be manipulated like any other window 


Set the width of the botton Margin with one of the following methods: 


- Move the left margin/indent marker over slightly and put a tab where 
the left margin/indent marker was • Press Tab up to 6 times to create 
a maximum of xx inches of space. 

” Click the double space box on the ruler and press Return once for a 
xx inch top margin, and twice for a xxinch margin. 


MacWrite allows you only to use the Return key twice to create the bottom 
margin, so you* 11 need to use 1 1/2 or double spacing to achieve a margin 
wider than two lines, or use Tab keys like Returns to create lines. 

Select an insertion point and type the text that you want repeated in the 
bottom margin. 

The footer may be edited like any other document. 

If you want the page number, date, or time to appear in the footer, 
position these icons: 

- the page 

- the date 

- the time 

Activate the document window. 

The footer is inserted into the document at the bottom of each page. The 
footer window moves behind the document window remaining barely visible at 
the bottom of the desktop, unless you have moved it. 

If you choose Hide Footer from the Format menu, the footer window 
disappears from the desktop and the footer disappears from your document. 
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87 


Automatic Pagination 


Mac Write numbers the pages of a document automatically and places the 
number in the header and footer where you’ve placed the pagination symbol. 


Choose Set Page Number from the Format menu* 


Type the number to be on the first printed page* 


A box appears asking for the page number. If you set the page number 
again in the same document, the box appears with the previous page number 
and asks you if you want to set a new one. 


Click OK «D0 IT» . 


The numbers appear in your document in the header or footer. 


PRINTING 

<<some of this is temporary>> 


Save your document if you want to keep a copy. 
Choose Print from the Folder menu. 

Click to make the check boxes look as follows: 


* Poper: 

J 

Rotn: 

Feed: 


Edit Search Formot style Fonts 

fTtocButhor 

3 Std US CRM 

«— i Legol (3 12“ Euro 

3 Tail n mtcle 

3 FanF old Sheet 


Special 




Figure 25 Printing 

Chose Quit from the Folder menu* 

Select PRAPP from MacStuff. 

Choose Print from the System menu. 
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accessory 


Any piece of equipment that connects to the Macintosh main unit other than 
the keyboard and the mouse# Accessories include additional disk drives, a 
keypad, and a printer. 


active selection 

The selection that will be affected by the next command* The active 
selection is highlighted. 


active window 

The frontmost window on the desk top. The window where the next action 
will take place. An active window's title bar is highlighted. 


alert nessage 

A warning message that appears in a window called an "alert box." Alert 
messages ,<<accompanied by an audible "beep,"» appear when you ask 
MacWrite to do something that may destroy some of your information or when 
your MacWrite can't interpret something you ask it to do. 


Backspace key 

A key on the MacWrite keyboard that backspaces over and erases the 
previously typed key. 


back up 

To make a copy of a disk. Backing up your disks ensures that you won't 
lose information in case a disk is lost or damaged. 


button 

A control that causes an action when clicked. Buttons appear in alert and 
dialog boxes and are sometimes used to confirm or cancel an action. 


calculator 

A desk accessory that works like a four-function pocket calculator. 
Calculation results can be cut and pasted into your document. 


cancel button 


A button that appears in alert or <<di.alog>> boxes . Clicking this button 
halts whatever action was in progress. 


Caps Lock key 

A key on the Macintosh keyboard that when engaged causes subsequently 
typed letters to appear in uppercase. 


character 

Anything that is inserted into a document from the character keys on the 
keyboard, including the Space bar, Return key, and Tab key. 


check box 

A control in the shape of a box, which may or may not have a check mark in 
it. Clicking in a check box may reverse its current state, or affect 
other related check boxes. 


choose 

To pick a menu item from a menu. Usually you do this after you've 
selected something for MacWrite to act on. 


clipboard 

The place that holds what was last cut or copied. The contents of the 
clipboard can always be viewed and pasted but not edited. 


click 

To position the pointer, then briefly press and release the mouse button. 


close 

To turn a document back into the icon that represents it. 


close box 

An icon on the left side of the title bar of some windows. When a close 
box is clicked, the window closes. 
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command 




A word <<or phrase>>, usually in a menu, describing an action for MacWrite 
to perform or a combination of keys on the keyboard accomplishing the same 
action. 


control panel 

A desk accessory. You use the control panel to change the speaker volume, 
the keyboard repeat speed and delay, and other preferences. 


cut 

To remove something from a document by selecting it and choosing Cut from 
a menu. What was cut is placed on the Clipboard. 

decimal tab 

A tab represented by the decimal tab marker that aligns columns of numbers 
at the decimal point position, or columns of words on the right. 


decimal tab marker 

An unfilled marker with a dot in it that you get from the decimal tab well 
and place under the number scale of the ruler. The marker indicates the 
position to which that Tab key will move the insertion point. 


desk accessories 

Items that are available on the desk top regardless of which tool you are 
using. Examples are the calculator, note pad, alarm clock, and puzzle. 


desktop 

MacWrite's working environment "the gray area on the screen and the menu 
bar. 




desktop manager 

A tool that allows you to get documents and copy, move, create, delete, 
and change the names of files. 


dinned item 

A menu item that appears dimmed compared to other items on the menu. A 
dimmed item cannot be chosen. 
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The magnetic medium that stores information. MacWrite*s disk is the 
<<Sony Macro Floppydisk Single Sided>>. 


disk drive 

The mechanism that holds the disk and retrieves information from it. 


document 

The contents of a document window. The information you enter, modify , 
view, or save. When these contents are stored on a disk, they are called 
files . 


document window 

A window that displays a document. 


double-click 

To position the pointer where you want the action to take place, then 
briefly press and release the mouse button twice in quick succession 
without moving the mouse. 


drag 

To position the pointer where you want the action to take place, press the 
mouse button, move the mouse, and release the mouse button. Releasing the 
mouse button after a drag either confirms a selection, moves an object to 
a new location, or does nothing if the mouse button is released at the 
same location as when it was first pressed. 


Enter key 

A key on the MacWrite keyboard that when pressed, confirms or terminates 
an entry. 


file 

A collection of information stored on a disk. 
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The name that you give a file. 


footer 

A footer is the bottom margin of a document. It is created separately 
from the body and can include text, graphics, automatic pagination, dates, 
and time that repeat on each page of the document. 


format 

Format is also used in MacWrite to mean determining the arrangement of 
text on a page: setting the margins, tabs, line spacing, and so forth 


get 

To bring a file into an application from the disk. 


graphics 

The display of images on the MacWrite screen. Information displayed in 
the form of pictures. 


header 

A header is the top margin of a document. It is created separately from 
the body and can include text, graphics, automatic pagination, dates, and 
time that repeat on each page of the document. 


highlight 

To make something that was black on a white background appear white on a 
black background and vice-versa. An item is usually highlighted to show 
that it has been selected or chosen. 


I-beam 

A type of pointer used in editing or inserting text. The I-beam marks the 
insertion point. 



icon 


A graphic representation of an object., a concept, or a message* A symbol 
with evident meaning. Icons are often objects associated with the desktop 
manager. 


inactive window 

Any window other than the active window that’s on the desktop. It will be 
behind the active window on the desktop. 


indent marker 

An arrow shaped marker that marks the position of the first line of a 
paragraph or any line that you end with the Return key. The indent marker 
can be to the inside or the outside of the left margin marker. 


insertion point 

The spot in a document where something will be added. An insertion point 
is selected by clicking and is marked by a blinking vertical bar. 


margin marker 

A blak triangle on each side of the ruler that can be moved to mark the 
left and right margin when setting a format text. The left margin marker 
appears stacked with the indent marker in a new document. 


memory 

The place in the MacWrite main unit that stores information while it’s 
working with it. 


menu 

A list of commands that appear when you point to and press the menu title 
in the menu bar. Dragging through the menu and releasing the mouse button 
while a menu item is highlighted chooses that item. 


menu bar 

The horizontal strip at the top of the screen that contains menu titles. 

menu Item 

One line in a menu. A menu item is usually a command for MacWrite to 
carry out. 
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menu title 




A word or phrase in the menu bar that designates one menu. Pressing on 
the menu title causes the title to be highlighted and its menu to appear 
below. 


mouse 

A device about the size of a deck of cards that you roll around on a flat 
surface next to your MacWrite. Moving the mouse causes corresponding 
motion of the position of the pointer on the screen. 


mouse button 

The square button on the top of the mouse. In general, pressing the mouse 
button initiates some action on whatever is under the position of the 
pointer, and releasing the button confirms the action. 


Note pad 

A desk accessory that allows you to enter and edit small amounts of text 
while working on another document* 


numeric keypad «?» 

An accessory keyboard containing arithmetic operator keys; used for 
numeric input* 

Option key 

A key on the MacWrite keyboard used like the Shift key. 
key gives an alternate interpretation to the key typed* 
foreign characters or special symbols. 

paste 

To put something back into a document that was cut or copied to the 
clipboard • 

point 

To position the pointer on something by moving the mouse* 

pointer 

A small shape on the screen, most often an arrow pointing to the 
upper-left corner of the screen which tracks the movement of the mouse. 


Using the Option 
It’s used to type 





press 


To position the pointer on something, then press and hold the mouse button 
without moving the mouse* 


Return key 

A key on the MacWrite keyboard that causes the current insertion point to 
move to the beginning of the next line. 

ruler 

A ruler appears at the top of all new MacWrite documents. You set format 
on rulers. In addition to this ruler, you can insert others throughout 
your document to vary the format. 

save 

To write information to a disk in order to have a permanent copy of it. A 
menu command that writes the current state of a document to a file on a 
disk. 

scroll 

To move a document so that a different part of it is visable. You use a 
window f s scroll bars to do this. 

scroll arrow 

A button on either end of a scroll bar with an arrow on it. Clicking a 
scroll arrow moves the document one line. Pressing the scroll arrow 
causes the document to scroll continuously. 

scroll bar 

A rectangular bar that may be at the right and bottom of a window. 

Clicking and dragging in the scroll bar causes the view of the document to 
change • 

select 

To click or drag over characters in a document or between two characters, 
or to click a window or icon to designate it to receive the next action. 

scroll box 

The position indicator on a scroll bar. The position of the scroll box in 
the scroll bar indicates the position of what's under the window relative 
to the length of the entire document. 
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space bar 


The long, unlabeled bar on the Macintosh keyboard* Pressing the space bar 
while typing puts a space at the insertion point. 

Tab key 

A key on the Macintosh keyboard simulates the functions of its typewriter 
counterpart . 

tab marker 

An unfilled triangle under the number scale of the ruler at the beginning 
of a new document that marks the position to which the tab key will move 
the insertion point. You get additional tabs by dragging them from the 
tab well. 

tab well 

A box on the lower right side of the ruler that holds tabs. 

title bar 

The horizontal bar at the top of a window that contains the name of the 
document. 

typeface 

A collection of letters, numbers, punctuation marks, and other 
typographical symbols with a consistent look. Examples of typefaces used 
with MacWrite include Helvetica and Bocklin. 

type style 

A stylistic variation of a typeface — italic, underline, shadow, or 
outline, for example. 


window 

Something that displays information on a desk top. Windows can be opened 
or closed. You can change their size and move them around. 


word wraparound 

At the right margin, words automatically move to the beginning of the next 
line as you type. It allows spacing in a paragraph to readjust when you 
edit. 
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